This is the full developer documentation for Teleflows Docs
# Everything you need to build on Teleflows.
> The Customer API reference, step-by-step guides and the MCP connector for AI assistants.
Guides
Create an API key, authenticate and page through lists. [Getting started](/guides/getting-started/) · [API Keys](/guides/api-keys/)
API reference
Every endpoint of the Teleflows Customer API, with parameters, responses and a request you can try. [Open the reference](/api-reference/)
MCP connector
Read your Teleflows data from Claude, ChatGPT and your IDE. [Connect Claude in 5 minutes](/guides/mcp/get-started/connect-claude/) · [Overview](/guides/mcp/)
## Popular
[Section titled “Popular”](#popular)
* [Create an API key](/guides/api-keys/#create-a-key)
* [Getting started](/guides/getting-started/)
* [List calls](/api-reference/#tag/calls/GET/api/v2/calls)
* [Connect Claude](/guides/mcp/how-to/connect-claude/)
* [Connect ChatGPT](/guides/mcp/how-to/connect-chatgpt/)
New to Teleflows? Visit [teleflows.io](https://teleflows.io/).
# Guides
> Step-by-step guides for the Teleflows Customer API.
Step-by-step guides for reading your Teleflows data with the Customer API.
Getting started
Create a key, authenticate and page through lists. [Getting started](/guides/getting-started/)
API Keys
Create, edit, revoke and replace your keys. [API Keys](/guides/api-keys/)
MCP connector
Read your Teleflows data from Claude, ChatGPT or your IDE. [Teleflows MCP connector](/guides/mcp/)
API reference
Every endpoint, parameter and response. [API reference](/api-reference/)
# API Keys
> Create, edit, revoke and replace your own Teleflows API keys.
Create and manage your own keys in **Settings → API Keys**.
## Create a key
[Section titled “Create a key”](#create-a-key)
1. Select **Create API key** and enter a name.
2. Keep your current role or choose another available role.
3. Choose an expiration date and time, then select **Create key**.
4. Use the copy icon to save the full key. It is shown only once.
5. Check **I have saved this key securely** and select **Done**.
## Roles and access
[Section titled “Roles and access”](#roles-and-access)
All user roles can create their own keys. A key cannot have more permissions or access to more records than you. Roles that exceed your access are not available.
You select a role for the key; you do not edit individual permissions here. Changes to your access can also affect the key.
## Expiration
[Section titled “Expiration”](#expiration)
Every key needs a future expiration date, no more than 365 days from now. There is no **Never** option. The date picker uses your local time; the list shows dates in your organization’s reporting timezone.
## Edit or revoke
[Section titled “Edit or revoke”](#edit-or-revoke)
**Edit:** Change the name, role or expiration, then select **Save changes**. The saved key stays the same.
**Revoke:** Select **Revoke**, then **Revoke key** to confirm. The key stops working and cannot be restored.
Expired and revoked keys cannot be edited or reactivated. Create a new key if needed.
## Status
[Section titled “Status”](#status)
| Status | Meaning |
| ------------ | ------------------------------------------------------------ |
| Active | Not expired or revoked; access still depends on permissions. |
| Expired | The expiration date has passed. |
| Revoked | The key has been permanently disabled. |
| Role removed | The assigned role no longer exists; the key cannot be used. |
## Replace a key
[Section titled “Replace a key”](#replace-a-key)
Create a new key, update your integration, confirm it works, then revoke the old key. If a key is exposed, revoke it immediately.
The shortened identifier in the list is not the full key. If you lose the full key, create a replacement.
# Echo
> Echo, the assistant inside Teleflows, reviews calls, ring tree targets, buyers and campaigns and answers questions from your call data.
Echo is the assistant inside the Teleflows app. It reviews a call, a ring tree target (RTT), a buyer or a campaign from the recorded evidence, answers your questions and suggests what to check next. Echo proposes; a person approves every change.
To start, [review your first call](/guides/echo/get-started/review-your-first-call/).
## Where to find Echo
[Section titled “Where to find Echo”](#where-to-find-echo)
* **The Echo button**: the Echo character in the bottom-right corner of app pages. It opens the Echo tray and shows “*n* to review” when something waits for you.
* **The command palette**: press **Ctrl K** (**Cmd K** on a Mac). Echo adds the sections **Commands**, **Ask Echo** and **Recent Echo conversations**. The palette is also in the workflow editor, which has no Echo button.
* **The Calls page**: **Review this call** in a call’s row menu, and **Ask Echo** in the call drawer.
* **Settings → Echo**: the Owner turns Echo on and sets its limits.
Review
[Review a call](/guides/echo/how-to/review-a-call/), or a [ring tree target, buyer or campaign](/guides/echo/how-to/review-rtt-buyer-campaign/).
Ask
[Ask Echo a question](/guides/echo/how-to/ask-a-question/) and [find past conversations](/guides/echo/how-to/find-past-conversations/).
Set up
The Owner [sets up Echo](/guides/echo/how-to/set-up-echo/) with the organization’s own Gemini key. [Who can use Echo](/guides/echo/concepts/who-can-use-echo/).
Reference
[Commands](/guides/echo/reference/commands/), [settings and limits](/guides/echo/reference/settings-and-limits/) and [messages](/guides/echo/reference/messages/).
# Echo proposes, a person approves
> What Echo can change, what it never does on its own, and how to see and undo a change.
“Echo proposes. A person approves.” Echo does not change your setup on its own.
## What Echo can change
[Section titled “What Echo can change”](#what-echo-can-change)
Only one thing: it can pause or resume a ring tree target **after a person approves** the proposal on a card. The change can be undone, and it is recorded in the Audit log. See [Answer and approve Echo cards](/guides/echo/how-to/act-on-echo-cards/).
## What Echo does not do
[Section titled “What Echo does not do”](#what-echo-does-not-do)
* It does not change routing or settings when it reviews a call, a ring tree target, a buyer or a campaign, or when it answers a question.
* It does not pause a target from a review. A review can only link to the target (“Consider pausing · Open *target*”); you decide.
* It does not search records you cannot read.
## Before and after
[Section titled “Before and after”](#before-and-after)
After an approved change, the card can compare the target before and after. This is an “Observed comparison · not causal”: it shows what happened next, not that the change caused it.
# How Echo answers
> Echo's answers rest on recorded evidence. Here is how to read the labels, the evidence and the limits.
Echo answers from the evidence Teleflows recorded: calls, bids, dials and routing decisions. It says what it saw, what it thinks may explain it and what it could not confirm.
## Labels on findings
[Section titled “Labels on findings”](#labels-on-findings)
| Label | Meaning |
| ---------------------------------- | ------------------------------------------- |
| Observed | Seen directly in the recorded evidence. |
| Projection | An estimate based on the evidence. |
| Possible explanation (or Possible) | A likely cause, not proven by the evidence. |
In a call review, each finding shows how many pieces of evidence support it. Hover a finding to see that evidence on the call’s timeline.
## Evidence and limits
[Section titled “Evidence and limits”](#evidence-and-limits)
* **Evidence and limits** lists the evidence used and what Echo is unsure about.
* **Things I couldn’t confirm** (call reviews) lists what the evidence did not show.
## Samples and windows
[Section titled “Samples and windows”](#samples-and-windows)
Echo reads a sample, not every call:
| Review | Window | Sample |
| ----------------------------------- | ------------------------------ | -------------------------------- |
| Ring tree target, buyer or campaign | Last 24 hours | Latest 1,000 calls |
| Similar calls (from a call review) | Last 24 h and the prior 7 days | Capped; “sample capped” when hit |
For a call review, Echo reads the evidence around the call’s own lifetime.
## Times
[Section titled “Times”](#times)
Times in reviews are in UTC.
# Who can use Echo
> Who sees Echo, which permissions each Echo action needs and what only the Owner can do.
## Who sees Echo
[Section titled “Who sees Echo”](#who-sees-echo)
Echo is in the Teleflows app for signed-in team members. It is not available to buyer or publisher portal users.
Echo also has to be turned on for the organization by the Owner. See [Set up Echo](/guides/echo/how-to/set-up-echo/).
## What each action needs
[Section titled “What each action needs”](#what-each-action-needs)
| Action | Needs |
| ----------------------------------------------------------------------- | -------------------------------------- |
| Ask Echo, review a call, RTT, buyer or campaign, see your conversations | Permission to read calls |
| Find a ring tree target, buyer or campaign to review | Permission to read that kind of record |
| Approve or undo a pause or resume | Permission to update ring tree targets |
| Answer an Owner question on a card | The Owner |
| Open Settings → Echo (turn Echo on, key, limits, usage) | The Owner |
## Echo sees what you can see
[Section titled “Echo sees what you can see”](#echo-sees-what-you-can-see)
* Reviews only find records your role can read. A call that is not in your call access is reported as not found.
* A phone number search matches tracking numbers, and caller numbers only if your role can see them.
* Your conversations are yours; other users do not see them.
If your permissions change during a conversation, Echo stops answering in it: start a new conversation.
# Review your first call
> Ask Echo to review a call from the Calls page and read its answer.
You need Echo turned on for your organization (the Owner does this in [Settings → Echo](/guides/echo/how-to/set-up-echo/)) and permission to read calls.
## 1. Pick a call
[Section titled “1. Pick a call”](#1-pick-a-call)
1. Open **Calls**.
2. Open the row menu of a call and choose **Review this call** (tooltip “Ask Echo to review this call”).
The command palette opens and Echo starts the review at once. While it works you see “Echo is examining the request.” and a **Cancel request** button.
## 2. Read the answer
[Section titled “2. Read the answer”](#2-read-the-answer)
The review shows, from top to bottom:
* the call, its result (for example **Converted** or **Didn’t connect**) and its revenue and payout,
* **The call, second by second**: bids, dials and routing on a timeline,
* Echo’s summary and **What I saw**: findings marked **Observed**, **Projection** or **Possible**,
* **Next step**, or **Nothing to change** when nothing on the call needs fixing,
* **Ask next**: one click for a follow-up such as **Check similar calls**.
[Review a call](/guides/echo/how-to/review-a-call/) explains every part.
## 3. Go back
[Section titled “3. Go back”](#3-go-back)
Choose **← Back to search** to leave the answer. The review stays in the Echo tray and under **Recent Echo conversations** in the palette.
Tip
You can also open a call and choose **Ask Echo** in the call drawer, or type `Review Call` followed by a call ID in the palette. See [Commands](/guides/echo/reference/commands/).
# Answer and approve Echo cards
> When Echo has investigated a ring tree target, it can leave cards in the Echo tray for you to answer, approve or decline.
When Echo has investigated a ring tree target (RTT), a card appears in the Echo tray. You may not see any cards: they come only from such investigations. With none, the tray says “Nothing from Echo yet today.” (or “Checking for updates…” while it loads).
## Where cards appear
[Section titled “Where cards appear”](#where-cards-appear)
In the Echo tray, under:
* **To review**: cards that wait for you,
* **Watching**: reviews in progress, with **Open target** and **Stop watching**,
* **Done today**: cards finished today.
When a new card arrives, the Echo button can show a short bubble, **Needs you** or **Suggestion**, with a **Review** button.
## Approve or decline a proposal
[Section titled “Approve or decline a proposal”](#approve-or-decline-a-proposal)
A proposal card suggests pausing or resuming one ring tree target and shows the change, for example Status **Active → Paused**. “Offer valid *m:ss*” counts down the time left to decide.
* **Approve pause** or **Resume *target***: Echo makes the change. A message “Echo applied” confirms it, with **Undo**.
* **Not now** or **Keep paused**: nothing changes.
You need permission to update ring tree targets to approve or undo. Without it the approve button is disabled and **Undo** does nothing.
If the proposal changed or expired before you chose, you see “This proposal changed or expired. Echo has refreshed the current receipt.”
## Undo
[Section titled “Undo”](#undo)
Choose **Undo** on the card or in the message. It reverses the pause or resume.
## Check the result
[Section titled “Check the result”](#check-the-result)
After a change, the card can compare the target before and after (“Observed comparison · not causal”). **View audit** opens the record of the change.
## Answer a question
[Section titled “Answer a question”](#answer-a-question)
A **Needs you** card asks a question. Choose an option or type an answer and choose **Send answer**. The card says whether it needs **Your answer** or an **Owner answer**, and until when it is open (UTC).
* Only the Owner can answer an Owner question: others see “Only the organization owner can answer this question.”
* If someone already answered: “That question is no longer pending. Echo has refreshed the current receipt.”
# Ask Echo a question
> Ask Echo a question in your own words, ask follow-ups and cancel a request.
## Ask
[Section titled “Ask”](#ask)
1. Press **Ctrl K** (**Cmd K** on a Mac), or choose **Ask Echo anything…** at the bottom of the Echo tray.
2. Type your question (at least 3 characters).
3. Choose **Ask Echo: “*your question*”**.
A question can be up to 4,000 characters; longer text is cut.
## Read the answer
[Section titled “Read the answer”](#read-the-answer)
The answer appears in the palette. It can show:
* findings marked **Observed**, **Projection** or **Possible explanation**,
* a recommendation,
* **Evidence and limits**: the evidence Echo used and what it is unsure about.
See [How Echo answers](/guides/echo/concepts/how-echo-answers/).
## Ask a follow-up
[Section titled “Ask a follow-up”](#ask-a-follow-up)
After an answer, the input reads “Ask a follow-up…”. Type and press **Enter**. Some answers also offer **Ask next** suggestions; choose one to ask it.
A conversation runs one request at a time. **Show earlier messages** loads older messages in a long conversation.
## Cancel a request
[Section titled “Cancel a request”](#cancel-a-request)
While Echo works (“Echo is examining the request.”), choose **Cancel request**. If the request has already finished you see “Could not cancel Echo’s request. It may already be complete.”
## Leave the answer
[Section titled “Leave the answer”](#leave-the-answer)
Choose **← Back to search**. The conversation is saved; see [Find past conversations](/guides/echo/how-to/find-past-conversations/).
# Find past conversations
> Open your earlier Echo questions and call reviews from the Echo tray or the command palette.
Your conversations are your own: other users do not see them.
## From the Echo tray
[Section titled “From the Echo tray”](#from-the-echo-tray)
1. Choose the Echo button in the bottom-right corner.
2. Your conversations are listed under **Today** and **Earlier**. Each row is a **Review** or a **Question** with its status:
| Status | Meaning |
| --------- | ---------------------------------------------------------------------------------------- |
| Running | Echo is working on it. |
| Answered | Echo answered. A call review shows the call’s result instead, for example **Connected**. |
| Failed | “Echo couldn’t finish. Try again.” |
| Cancelled | “Cancelled before Echo answered”. |
3. Choose a row to open it in the palette.
With no conversations yet, the tray says “Your questions and call reviews will appear here.” Choose **Show more conversations** for older ones.
## From the command palette
[Section titled “From the command palette”](#from-the-command-palette)
Press **Ctrl K** (**Cmd K** on a Mac). Under **Recent Echo conversations**:
* **New Echo conversation** starts a fresh one.
* Your saved conversations by title (“Untitled Echo conversation” when there is none).
* **Show more conversations** loads older ones.
# Review a call
> Three ways to ask Echo to review a call, and what each part of the call review shows.
## Start a review
[Section titled “Start a review”](#start-a-review)
Use any of these:
* **Calls page, row menu**: choose **Review this call**. The review starts at once.
* **Call drawer**: open a call and choose **Ask Echo** (tooltip “Investigate this call with Echo”). The palette opens with “Ask Echo about call *number*…”; type your question about this call.
* **Command palette**: type `Review Call` followed by a phone number or a call ID, then press **Enter**. A call ID finds a call from any date; a phone number finds only today’s calls. See [Commands](/guides/echo/reference/commands/).
Echo is asked to explain the call’s outcome, buyer responses, connection attempts and routing decisions, to say what information is missing and to suggest next steps without changing routing.
## Read the call review
[Section titled “Read the call review”](#read-the-call-review)
### Header
[Section titled “Header”](#header)
The call (or its target), the routing type, the start time in UTC and the duration. Revenue and payout are shown when recorded.
The result pill is one of:
| Result | When |
| --------------- | -------------------------------------------------------------- |
| Converted | The call converted. |
| Connected | The call connected but did not convert. |
| Didn’t connect | A buyer accepted, but the call did not connect. |
| No accepted bid | Buyers were pinged or targets dialed, but no bid was accepted. |
| No trace | No bids or dials were recorded for the call. |
### The call, second by second
[Section titled “The call, second by second”](#the-call-second-by-second)
A timeline of the call with three rows: **Bids**, **Dials** and **Routing**. Hover a finding to see its evidence on the timeline.
### What I saw
[Section titled “What I saw”](#what-i-saw)
Echo’s summary, then its findings. Each finding is marked **Observed**, **Projection** or **Possible** and shows how many pieces of evidence support it. See [How Echo answers](/guides/echo/concepts/how-echo-answers/).
### Routing pass 1
[Section titled “Routing pass 1”](#routing-pass-1)
The candidates of the first routing pass, ranked, with the winner marked **WON** and a “Priority-adjusted ratio” note. The heading also says how many passes ran.
### Next step
[Section titled “Next step”](#next-step)
Echo’s suggested next step. When nothing needs fixing it says **Nothing to change**: “Nothing on this call needs fixing.”
### Things I couldn’t confirm
[Section titled “Things I couldn’t confirm”](#things-i-couldnt-confirm)
A list of what Echo could not confirm from the recorded evidence. Hover an item for the detail.
### Ask next
[Section titled “Ask next”](#ask-next)
* Echo’s own follow-up question, when it has one. Choose it to put it in the input.
* **Check similar calls**: compares this call’s ring tree target with the other targets in its ring tree.
## Similar calls
[Section titled “Similar calls”](#similar-calls)
After **Check similar calls**, the review shows the connect rate of **This target** and of **Peers in its ring tree** for the **Last 24 h** and the **Prior 7 days**, with notes such as:
* “Deterioration is specific to this target”
* “Peers unchanged”
* “Traffic mix shifted”
* “Not enough comparable traffic to judge.”
“all traffic, not matched by campaign” means the peers’ calls were not limited to the reviewed call’s campaign. “sample capped” means a column hit the sample limit.
**View affected calls** (with the number affected) opens those calls on the Calls page. A link opens the target. When this target got worse and its peers did not, the link reads “Consider pausing · Open *target*”. Echo does not pause anything itself.
# Review a ring tree target, buyer or campaign
> Ask Echo to review a ring tree target (RTT), a buyer or a campaign, and read its summary.
## Start a review
[Section titled “Start a review”](#start-a-review)
1. Press **Ctrl K** (**Cmd K** on a Mac).
2. Type `Review`, then `RTT`, `Buyer` or `Campaign`. **Tab** completes each word.
3. Type a name or an ID. Matching records appear while you type.
4. Choose the record to review.
“Enter a name or ID. Echo starts only after the object is verified.” Echo only finds records you can read. If nothing matches, nothing is sent to Echo.
Echo is asked to summarize the record’s current status and recorded call performance, to state the reporting window and missing evidence and to suggest next checks without changing routing or settings.
## Read the review
[Section titled “Read the review”](#read-the-review)
### Recorded call outcomes
[Section titled “Recorded call outcomes”](#recorded-call-outcomes)
By default the review covers the last 24 hours, using the latest 1,000 calls (“Latest 1000 calls; sample only” when the sample is full; otherwise “Within your call access”).
| Row | Meaning |
| --------------------------------- | ------------------------------------------------------------------------------- |
| Calls sampled | Calls in the sample. |
| Completed / In progress | Calls that have ended, and calls still live. |
| Connected completed calls | Ended calls that connected. |
| Converted completed calls | Ended calls that converted. |
| Connection rate · completed calls | Connected ÷ completed. “Unavailable” when it cannot be worked out. |
| Pings / Accepted / Unknown | RTT reviews only: ping requests, accepted pings and pings with no known answer. |
### Findings
[Section titled “Findings”](#findings)
Each finding is marked **Observed** or **Possible explanation**. Then **Suggested next step** and **Evidence and limits**.
### Ask next
[Section titled “Ask next”](#ask-next)
* **What should I check next?**
* **Compare previous period**: compares with the preceding 24 hours.
* **Acceptance vs connections** (RTT reviews only): explains the difference between ping acceptance and connected calls.
# Set up Echo
> The Owner turns Echo on for the organization, adds a Gemini key and sets Echo's limits.
Only the organization’s Owner can do this. Echo is off for an organization until the Owner turns it on.
## Open Settings → Echo
[Section titled “Open Settings → Echo”](#open-settings--echo)
Open **Settings** and choose the **Echo** tab, or choose the settings icon in the Echo tray. The page header shows Echo’s status: **Not set up**, **On** or **Off**.
Other users who open the page see “Owner access required”.
## Two steps
[Section titled “Two steps”](#two-steps)
“Save a policy, then add a Gemini key.”
### 1. Save a policy
[Section titled “1. Save a policy”](#1-save-a-policy)
1. Turn on **Enable Echo**.
2. Choose an **Effort**: **Essential**, **Balanced** or **Deep**.
3. Check the limits. The defaults are fine to start; see [Settings and limits](/guides/echo/reference/settings-and-limits/).
4. Choose **Save changes**. You see “Echo policy saved.”
### 2. Add a Gemini key
[Section titled “2. Add a Gemini key”](#2-add-a-gemini-key)
Echo uses the organization’s own Gemini key.
1. Under **Provider**, choose **Add key**.
2. Choose **Gemini**. Claude and ChatGPT are shown as “Coming soon”.
3. Paste the key and choose **Save key**.
The key is “Stored encrypted. Only the masked ending is shown.”
If Echo is on but has no active key, the page says “On, but no key.” (or “The provider key is disabled.”) with an **Add key** or **Replace key** button.
## Replace or disable the key
[Section titled “Replace or disable the key”](#replace-or-disable-the-key)
* **Replace key**: save a new key in place of the current one.
* **Disable**: confirm “Disable this key? Echo will not be able to make model requests with it.” Echo then cannot make model requests until you add an active key.
## Turn Echo off
[Section titled “Turn Echo off”](#turn-echo-off)
Turn off **Enable Echo** and choose **Save changes**.
# Commands
> The Review command in the command palette, with its record types and lookup rules.
Commands are typed in the command palette (**Ctrl K**, **Cmd K** on a Mac). They appear under **Commands**.
## Review
[Section titled “Review”](#review)
```plaintext
Review
```
| Type | You enter | Finds |
| -------- | --------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Call | A call ID, or a full phone number with country code | A call ID: a call from any date. A phone number: today’s calls only, by tracking number (and by caller number if your role can see caller numbers), newest first. “Today” follows your reporting time zone. |
| RTT | A ring tree target’s name or ID | Ring tree targets you can read. |
| Buyer | A buyer’s name or ID | Buyers you can read. |
| Campaign | A campaign’s name or ID | Campaigns you can read. |
## Keys
[Section titled “Keys”](#keys)
| Key | Does |
| ----- | -------------------------------------------------------------------------------- |
| Tab | Completes the next word (`Review`, then the type). |
| Enter | Looks up the record. With one match the review starts; with several, choose one. |
| Esc | Closes the palette. |
## Lookup rules
[Section titled “Lookup rules”](#lookup-rules)
* For RTT, Buyer and Campaign, matches appear while you type; for Call, press **Enter**.
* At most 10 matches are shown. “More matches are available. Refine the name or enter an exact ID.”
* With one exact match, the review starts. With several, “Choose the object to review.”
* Nothing is sent to Echo until the record is verified.
* A phone number without its country code, or text that looks like an ID but is not a valid one, shows “Could not verify this *type*. …”.
* A misspelled type shows “Choose Call, RTT, Buyer, or Campaign”.
See [Messages](/guides/echo/reference/messages/) for what each lookup message means.
# Messages
> Messages Echo can show and what to do about each one.
## Looking up a record
[Section titled “Looking up a record”](#looking-up-a-record)
| Message | What it means | What to do |
| --------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- |
| No accessible call found. Phone numbers search today only; a call ID can match any date. | No call you can read matches. | Use the call ID for older calls. See [Commands](/guides/echo/reference/commands/). |
| No accessible *type* found. Check its name or ID. Nothing was sent to Echo. | No RTT, buyer or campaign you can read matches. | Check the name or ID. |
| Could not verify this *type*. Check the name or ID and your access. Nothing was sent to Echo. | The lookup failed, for example a phone number without its country code or an ID that is not valid. | Enter the full phone number with country code, the whole ID or the name, then try again. |
| More matches are available. Refine the name or enter an exact ID. | More than 10 matches. | Type more of the name, or the ID. |
## Asking and answers
[Section titled “Asking and answers”](#asking-and-answers)
| Message | What it means | What to do |
| ------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------- |
| Echo is examining the request. | Echo is working. | Wait, or choose **Cancel request**. |
| Echo accepted the request. Waiting for its live result. | The request was saved; the answer has not arrived yet. | Wait. Do not send it again. |
| Could not confirm Echo’s request. Retry safely. | The request was not confirmed, for example because Echo is off, a limit is reached or the connection failed. | Try again. See [Troubleshooting](/guides/echo/troubleshooting/). |
| Could not cancel Echo’s request. It may already be complete. | The request had already finished. | Read the answer. |
| Echo could not complete this request. | Echo failed on this request. | Ask again. |
| This request was cancelled. | You cancelled it. | Ask again if needed. |
| Could not load earlier messages. Try again. | Older messages did not load. | Try again. |
| Could not load saved Echo conversations. Try again. | The conversation list did not load. | Choose it to try again. |
| Could not open this conversation. Try again. | The conversation did not open. | Try again. |
## Echo tray
[Section titled “Echo tray”](#echo-tray)
| Message | What it means |
| ------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
| *n* to review · live | *n* cards wait for you; the tray is receiving live updates. |
| … · connecting… | The tray is connecting for live updates. |
| … · offline | Live updates stopped; the tray reconnects on its own. |
| Checking for updates… | The tray is loading. |
| Nothing from Echo yet today. | No cards. |
| Your questions and call reviews will appear here. | You have no conversations yet. |
| Could not load conversations. Try again. | The list did not load; choose it to try again. |
| Echo could not be refreshed. | Cards did not refresh. |
| Your organization has reached its … limit. Resets … UTC. An organization owner can adjust this in Settings → Echo → Caps. | An organization limit is reached. See [Settings and limits](/guides/echo/reference/settings-and-limits/#when-a-limit-is-reached). |
## Cards
[Section titled “Cards”](#cards)
| Message | What it means |
| --------------------------------------------------------------------------- | ---------------------------------------- |
| This proposal changed or expired. Echo has refreshed the current receipt. | The proposal is no longer current. |
| The action was not accepted. Echo has refreshed the current receipt. | The approval or undo was refused. |
| Only the organization owner can answer this question. | The question needs the Owner. |
| That question is no longer pending. Echo has refreshed the current receipt. | Someone already answered, or it expired. |
## Settings → Echo
[Section titled “Settings → Echo”](#settings--echo)
| Message | What it means |
| ----------------------------------------------------------------------- | ------------------------------------------------------------------ |
| Owner access required | Only the Owner can open Echo settings. |
| On, but no key. / The provider key is disabled. | Echo is on but cannot make model requests. Add or replace the key. |
| Disable this key? Echo will not be able to make model requests with it. | Confirmation before disabling the key. |
# Settings and limits
> Every field on Settings → Echo, Echo's default organization limits and what happens when one is reached.
**Settings → Echo** is for the Owner only. See [Set up Echo](/guides/echo/how-to/set-up-echo/).
## Investigation policy
[Section titled “Investigation policy”](#investigation-policy)
“Echo proposes. A person approves.” A link opens the **Audit log**.
| Field | What it sets |
| ----------------------- | -------------------------------------------------------------------------------------------- |
| Enable Echo | Turns Echo on or off for the organization. |
| Effort | **Essential** (Quick look), **Balanced** (Usual) or **Deep** (Thorough). |
| Run deadline | Maximum time for one investigation: 5, 10, 15 or 30 min, or **Custom** (1 to 3,600 seconds). |
| Investigations at once | How many investigations can run at the same time. |
| Tool runs at once | How many tool runs one investigation can have at the same time. |
| Requests, Tokens, Spend | Ceilings for one investigation. Spend is optional (“No cap”). |
## Provider
[Section titled “Provider”](#provider)
| Field | What it sets |
| -------- | -------------------------------------------------------------------------------------------------- |
| Provider | **Gemini**. Claude and ChatGPT are “Coming soon”. |
| Key | The organization’s Gemini key. “Stored encrypted. Only the masked ending is shown.” |
| Model | The model name; “Backend default” when empty. “Reasoning depth is chosen from the effort setting.” |
## Caps
[Section titled “Caps”](#caps)
“For the whole organization.”
| Cap | Default |
| --------------------------- | ----------------- |
| Requests per day | 100 |
| Requests per month | 2,000 |
| Tokens per day | 1,000,000 |
| Tokens per month | 20,000,000 |
| Spend per day / per month | No cap (optional) |
| Requests per minute | 10 |
| Tokens per minute | 100,000 |
| Evidence queries per minute | 60 |
| Model requests at once | 2 |
## Saving
[Section titled “Saving”](#saving)
Changes show an **Unsaved changes** bar: “Applies to new investigations. Current limits are rechecked.” Choose **Save changes** or **Discard**.
## Usage
[Section titled “Usage”](#usage)
The **Usage** panel shows what the organization has used against each cap. “Held is reserved for a request in flight.” With no usage yet: “No admitted usage recorded yet.”
## When a limit is reached
[Section titled “When a limit is reached”](#when-a-limit-is-reached)
Everyone in the organization sees, in the Echo tray and in a bubble from the Echo button titled **Organization limit reached**:
> Your organization has reached its *monthly / daily / per-minute* *model request / token / spend* limit. Resets *date, time* UTC. An organization owner can adjust this in Settings → Echo → Caps.
For example: “Your organization has reached its daily model request limit.”
The bubble’s **View Echo** opens the tray. New requests are refused until the limit resets or the Owner raises it.
# Troubleshooting
> Fixes for the most common Echo problems.
## I don’t see Echo
[Section titled “I don’t see Echo”](#i-dont-see-echo)
* Buyer and publisher portal users do not have Echo.
* Asking and reviewing need permission to read calls. Ask your admin.
* The workflow editor has no Echo button; use **Ctrl K** (**Cmd K** on a Mac) there.
See [Who can use Echo](/guides/echo/concepts/who-can-use-echo/).
## I don’t see Settings → Echo
[Section titled “I don’t see Settings → Echo”](#i-dont-see-settings--echo)
Only the Owner sees the Echo tab in Settings.
## “Could not confirm Echo’s request. Retry safely.”
[Section titled ““Could not confirm Echo’s request. Retry safely.””](#could-not-confirm-echos-request-retry-safely)
The request was not confirmed. Common causes:
* Echo is not turned on for the organization, or it has no active key. Ask the Owner to check [Settings → Echo](/guides/echo/how-to/set-up-echo/).
* An organization limit is reached. The Echo tray says which one and when it resets.
* The connection dropped. Try again.
## A phone number finds no call
[Section titled “A phone number finds no call”](#a-phone-number-finds-no-call)
A phone number only finds today’s calls. Use the call ID for older calls. See [Commands](/guides/echo/reference/commands/).
## “Organization limit reached”
[Section titled ““Organization limit reached””](#organization-limit-reached)
The organization used up a cap. It resets at the time shown, or the Owner can raise it in **Settings → Echo → Caps**. See [Settings and limits](/guides/echo/reference/settings-and-limits/).
## The tray says “offline”
[Section titled “The tray says “offline””](#the-tray-says-offline)
Live updates stopped. The tray reconnects on its own.
## No cards in the tray
[Section titled “No cards in the tray”](#no-cards-in-the-tray)
Cards appear only when Echo has investigated a ring tree target. Reviews and questions are listed as conversations, not cards. See [Answer and approve Echo cards](/guides/echo/how-to/act-on-echo-cards/).
# Getting started
> Create an API key, authenticate with the X-API-Key header and page through lists.
1. Open **Settings → API keys** and create a key.
2. Choose its role and an expiry within one year. Only roles whose permissions fit within your own are available.
3. Copy the key and save it securely. You can only see the full key once.
4. Set `TELEFLOWS_API_KEY` in your environment, then send a request:
```sh
curl "https://api.teleflows.io/api/v2/campaigns?page=1&page_size=20" \
-H "X-API-Key: $TELEFLOWS_API_KEY"
```
More about keys, roles, expiry and revoking: [API Keys](/guides/api-keys/).
## Public campaign offers
[Section titled “Public campaign offers”](#public-campaign-offers)
Browse published campaign offers without an API key or login:
```sh
curl "https://api.teleflows.io/api/v2/public/campaign-offers?page=1&page_size=20"
```
The JSON response lists each campaign’s ID, name, country and `estimated_payout_per_call` range (`min`, `max`, `currency`). Amounts are decimal strings. No organization parameter is needed. Filter with `search` or a two-letter uppercase `country_code`. Page size is at most 100 and page number is at most 1000.
Estimates describe publisher earnings per incoming call, including unpaid calls. By default, they use seven days of mature history, refresh once per day and show a range 25% either side of the historical average. Fewer than 30 calls produce a wider 50% range. Missing history or negative total payouts return a null range. Campaign eligibility is checked on each request. Individual publisher terms can differ; the range is an estimate rather than a guaranteed rate.
This endpoint accepts JSON only and has a separate anonymous request limit. Follow `Retry-After` on a 429 response. Account endpoints below still require an API key.
## Authentication and access
[Section titled “Authentication and access”](#authentication-and-access)
Send your key in the `X-API-Key` header. These endpoints support GET requests only. Do not add a Bearer token. Your key can only read records allowed by both your current role and its assigned role. Use the paths in the [API reference](/api-reference/) for integrations.
To rotate a key, create a replacement, update your integration, then revoke the old key in Settings. Expired and revoked keys cannot make requests.
## Pagination and dates
[Section titled “Pagination and dates”](#pagination-and-dates)
Entity lists accept `page` (starting at 1) and `page_size` (up to 100). Responses include `items`, `total`, `page`, `page_size` and `pages`. Continue until you reach the last page. Available filters are listed on each endpoint. Timestamps use ISO 8601 with a timezone offset.
## Errors and limits
[Section titled “Errors and limits”](#errors-and-limits)
| Status | What to do |
| ------ | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| 401 | Check your key, expiry and revocation status. |
| 403 | Your key cannot perform this operation. |
| 404 | The resource does not exist or is outside your access. |
| 405 | Use the documented GET method. |
| 422 | Correct the parameter identified in the response. |
| 429 | Wait for the `Retry-After` duration before retrying. Your API keys share an API request allowance that is separate from your browser activity. |
| 503 | A required service is temporarily unavailable; retry later. |
## Try a request
[Section titled “Try a request”](#try-a-request)
Open an endpoint in the [API reference](/api-reference/), enter your API key and select **Test Request**. The request goes directly to your API. Your key is kept in that page’s memory; it is not saved between visits.
# Teleflows MCP
> Read your Teleflows data from Claude, ChatGPT and your IDE.
# Ask Teleflows in plain language.
Read-only answers from your own data in Claude, ChatGPT and your IDE.
[Connect Claude](/guides/mcp/get-started/connect-claude/)[All apps](/guides/mcp/how-to/other-apps/)
Works with Claude, ChatGPT, Claude Code and other MCP apps
Which buyers converted best yesterday?
Teleflows Example data
* Buyer A42 conversions
* Buyer B35 conversions
* Buyer C28 conversions
The Teleflows MCP connector lets an AI assistant read your Teleflows data with your own API key. To start, [connect Claude in 5 minutes](/guides/mcp/get-started/connect-claude/).
Connect
Add the server to [Claude](/guides/mcp/how-to/connect-claude/), [ChatGPT](/guides/mcp/how-to/connect-chatgpt/), [Claude Code](/guides/mcp/how-to/connect-claude-code/) or [other apps](/guides/mcp/how-to/other-apps/).
Ask questions
Ask about calls, campaigns, buyers and reports in plain language. [Start here](/guides/mcp/get-started/connect-claude/).
Secure by design
Read-only tools, your own API key and your role’s permissions. [How it works](/guides/mcp/concepts/sign-in-and-security/).
Reference
Every [tool](/guides/mcp/reference/tools/), [limit](/guides/mcp/reference/limits/) and [message](/guides/mcp/reference/messages/).
# Privacy and data
> What the Teleflows MCP server stores, what it logs, and where your answers are produced.
The Teleflows MCP server reads your Teleflows data when your assistant asks for it and passes it on. It keeps as little as possible.
## What is stored
[Section titled “What is stored”](#what-is-stored)
Only what sign-in needs:
* **Your API key, encrypted.** Each key is encrypted with its own data key, and that data key is itself encrypted with the server’s master key.
* **Sign-in codes and tokens, only as hashes.** The same goes for sign-ins in progress. A stored hash cannot be turned back into a code or token.
No Teleflows data is stored: no calls, no names and no responses.
## How long it is kept
[Section titled “How long it is kept”](#how-long-it-is-kept)
* Expired sign-in data is removed automatically.
* When a connection is revoked, its stored key is wiped at once. When a connection expires, its key is wiped at the next cleanup.
* The rest of an ended connection’s record is deleted 30 days later.
* The sign-in database is backed up nightly, and the newest 14 backups are kept. They hold only encrypted keys and hashed tokens.
## What is logged
[Section titled “What is logged”](#what-is-logged)
One line per request: the method, the path, the status, how long it took, whether a sign-in token was sent, and the app’s user agent.
The log never contains query strings, keys, tokens or request and response bodies.
## Where answers are produced
[Section titled “Where answers are produced”](#where-answers-are-produced)
Answers are produced by your AI assistant. The data a tool returns is sent to that assistant’s provider, for example Anthropic or OpenAI, and handled under their terms.
Tip
Your key’s role limits what any assistant can read. See [Roles and access](/guides/mcp/concepts/roles-and-access/).
To stop access, see [Revoke access](/guides/mcp/how-to/revoke-access/).
# Roles and access
> Your API key's role decides what the assistant can see.
The assistant sees exactly what your API key’s role can see. The role is set when you [create the key](/guides/mcp/how-to/create-api-key/). Only roles whose permissions fit within your own are available.
## Choosing a role
[Section titled “Choosing a role”](#choosing-a-role)
* Pick a role that can read the data you want to ask about: calls, campaigns, routing, reports.
* Read-only use never needs a role that can change data. The server cannot change anything in any case.
## When the role sees less
[Section titled “When the role sees less”](#when-the-role-sees-less)
With a smaller role, some questions are answered with:
* fewer records,
* an empty list, or
* “Your API key’s role cannot use this. Ask a Teleflows admin for a key with more access.”
Some fields can be missing or masked for your role, for example caller numbers or money fields. The assistant says so instead of treating them as zero.
Note
Teleflows decides what each role can see. The server passes on what Teleflows returns for your key and does not widen or narrow it.
# Server address
> The address of the Teleflows MCP server and which Teleflows keys it accepts.
Add this address to your app:
```plaintext
https://mcp.teleflows.io
```
It reads Teleflows production, so sign in with a key from Teleflows production.
Note
If your Teleflows team gave you a test address, use a key from that test environment. Keys from another Teleflows environment are refused with “Teleflows did not accept this key.”
The sign-in page names the Teleflows address the server reads, so you can check that your key comes from the right place.
# Sign-in and security
> How you sign in with your API key, where the key is kept and what the sign-in page shows.
## How sign-in works
[Section titled “How sign-in works”](#how-sign-in-works)
Your app connects with OAuth, the standard sign-in method for MCP servers. When you connect, the Teleflows MCP server opens a sign-in page in your browser. You paste your Teleflows API key there, not into the app.
The server checks the key with Teleflows before it accepts it. After sign-in, you return to your app.
## Where your key is kept
[Section titled “Where your key is kept”](#where-your-key-is-kept)
* The key is stored encrypted on the Teleflows MCP server.
* It is used only to read data for you, within what its role allows.
* The assistant never sees the key.
* A connection lasts up to 90 days. After that, you sign in again.
## Read-only
[Section titled “Read-only”](#read-only)
The server is read-only. Nothing in Teleflows can be created, changed or deleted through it. Requests to change something are refused.
## Check the sign-in page
[Section titled “Check the sign-in page”](#check-the-sign-in-page)
Before you paste your key, check what the sign-in page shows:
* **The app.** It names the app you are connecting, and the website that identifies it, for example **ChatGPT (identified by chatgpt.com)**.
* **The return address.** After you connect, you are sent to this address, for example **claude.ai** or **chatgpt.com**.
* **Unverified apps.** An app marked **unverified app** chose its own name. Continue only if you started the connection yourself and recognise the address.
Caution
Only continue if you started the connection from your own app. If you did not, select **Cancel**.
A sign-in must be finished within 10 minutes, in the browser window that started it. After 5 wrong keys, the sign-in stops and you start again from your app.
## Stop access
[Section titled “Stop access”](#stop-access)
See [Revoke access](/guides/mcp/how-to/revoke-access/).
# Connect Claude in 5 minutes
> Create a Teleflows API key, add the Teleflows MCP server to Claude and ask your first question.
In this tutorial you connect Claude to your Teleflows data and ask a first question. You need a Teleflows account and a Claude account. It takes about five minutes.
You will:
1. Create a Teleflows API key.
2. Add the Teleflows connector in Claude.
3. Sign in with your key.
4. Ask Claude about your buyers.
Note
The Teleflows MCP server is read-only. Nothing in Teleflows can be created, changed or deleted through it.
## 1. Create an API key
[Section titled “1. Create an API key”](#1-create-an-api-key)
1. In Teleflows, open **Settings → API keys** and create a key.
2. Name it after the app, for example **Claude**.
3. Choose a role and an expiry. The role decides what Claude can see. See [Roles and access](/guides/mcp/concepts/roles-and-access/).
4. Copy the key. You can only see the full key once.
More detail: [Create a Teleflows API key](/guides/mcp/how-to/create-api-key/).
## 2. Add the connector
[Section titled “2. Add the connector”](#2-add-the-connector)
1. In Claude, open **Settings → Connectors** and choose **Add custom connector**.
2. Enter the name **Teleflows** and the server address:
```plaintext
https://mcp.teleflows.io
```
3. Select **Add**, then **Connect**.
## 3. Sign in
[Section titled “3. Sign in”](#3-sign-in)
A Teleflows sign-in page opens.
1. Check that it names **Claude** and that you will be sent back to **claude.ai**.
2. Paste your API key and select **Connect**.
You return to Claude, and the connector shows as connected.
Tip
If Claude says the connector “wasn’t connected” right after you sign in, reload the page. The connector is usually already connected.
## 4. Ask your first question
[Section titled “4. Ask your first question”](#4-ask-your-first-question)
Start a new chat. If Teleflows is off in this chat, select **+**, choose **Connectors** and turn it on. Then ask:
> List my buyers in Teleflows
Claude asks before it uses a Teleflows tool. Allow it. To stop the questions, set the tools to **Always allow** under [Tool permissions](/guides/mcp/how-to/connect-claude/#tool-permissions).
Claude reads your buyers and answers with a list from your account.
A good answer:
* Lists buyers you recognise from Teleflows.
* Says so when a field is missing or masked for your key’s role, instead of treating it as zero.
* Says so when Teleflows does not document what a value means, instead of guessing.
## What to ask next
[Section titled “What to ask next”](#what-to-ask-next)
| Area | For example |
| ---------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| Calls | “Show my last 10 calls” · “How many calls yesterday, by campaign?” · “Is there a recording for this call?” |
| Campaigns | “List my active campaigns” · “Which publishers send traffic to campaign X?” · “Which tracking numbers belong to campaign X?” |
| Routing | “Which buyers are active?” · “Show the routing plan for campaign X” · “What are the caps and recent pings for ring tree target X?” |
| Setup | Workflows, variables, audio files, blocked numbers, pixels, postback and predictive configs |
| Monitoring | “Show this week’s conversion receipts” · “Where is target X used?” |
Questions cover up to 31 days at a time, in UTC. See [Limits](/guides/mcp/reference/limits/).
## Next steps
[Section titled “Next steps”](#next-steps)
* See every tool the assistant can use: [Tools](/guides/mcp/reference/tools/).
* Learn [how sign-in keeps your key safe](/guides/mcp/concepts/sign-in-and-security/).
* Connect [ChatGPT](/guides/mcp/how-to/connect-chatgpt/) or [Claude Code](/guides/mcp/how-to/connect-claude-code/).
# Connect ChatGPT
> Add the Teleflows MCP server to ChatGPT in developer mode.
ChatGPT connects to the Teleflows MCP server in developer mode, which is available on paid plans.
1. Open **Settings → Apps & Connectors → Advanced settings** and turn on **Developer mode**.
2. Add a new app or connector. Enter a name, such as **Teleflows**, and the server address:
```plaintext
https://mcp.teleflows.io
```
3. Choose **OAuth** as the authentication.
4. Sign in on the Teleflows page that opens. Check that it shows **ChatGPT (identified by chatgpt.com)** and returns to **chatgpt.com**, then paste your [API key](/guides/mcp/how-to/create-api-key/) and select **Connect**.
# Connect Claude
> Add the Teleflows MCP server to Claude as a custom connector.
Use these steps for claude.ai and the Claude apps.
1. Open **Settings → Connectors** and choose **Add custom connector**.
2. Enter a name, such as **Teleflows**, and the server address:
```plaintext
https://mcp.teleflows.io
```
3. Select **Add**, then **Connect**.
4. Sign in on the Teleflows page that opens. Check that it names Claude and returns to **claude.ai**, then paste your [API key](/guides/mcp/how-to/create-api-key/) and select **Connect**.
## Use it in a chat
[Section titled “Use it in a chat”](#use-it-in-a-chat)
In a chat, select the **+** button, choose **Connectors**, and turn **Teleflows** on or off for that conversation.
## Tool permissions
[Section titled “Tool permissions”](#tool-permissions)
After you connect, open **Settings → Connectors** and select the Teleflows connector. Under **Tool permissions**, the group **Read-only tools** lists all 28 tools, set to **Needs approval** by default.
For each tool you can choose:
* **Always allow**: Claude uses the tool without asking.
* **Needs approval**: Claude asks you before each use.
* **Blocked**: Claude cannot use the tool.
Team and Enterprise plans
An organization owner adds the connector first. Each member then connects with their own key.
Tip
If Claude says the connector “wasn’t connected” right after you sign in, reload the page. The connector is usually already connected.
# Connect Claude Code
> Add the Teleflows MCP server to Claude Code from the terminal.
1. Run this in a terminal:
```sh
claude mcp add --transport http teleflows https://mcp.teleflows.io
```
2. In Claude Code, run `/mcp`, choose **teleflows** and sign in.
3. The Teleflows sign-in page opens in your browser. Paste your [API key](/guides/mcp/how-to/create-api-key/) and select **Connect**.
Note
The sign-in page shows a `localhost` return address for Claude Code. This is normal: Claude Code receives the sign-in on your own computer.
# Create a Teleflows API key
> Create the Teleflows API key you use to sign in to the Teleflows MCP server.
You sign in to the Teleflows MCP server with a Teleflows API key. The key’s role decides what your assistant can see.
1. In Teleflows, open **Settings → API keys** and create a key.
2. Name it after the app, for example **Claude** or **ChatGPT**.
3. Choose a role. Only roles whose permissions fit within your own are available. See [Roles and access](/guides/mcp/concepts/roles-and-access/).
4. Choose an expiry, up to one year.
5. Copy the key. You can only see the full key once.
Tip
Create a separate key for each app. You can then revoke one without affecting the others.
Caution
Create the key in the same Teleflows environment that the server reads. Keys from another Teleflows environment are not accepted. See [Server address](/guides/mcp/concepts/server-address/).
Keys start with `tfk_`.
More about keys, roles and expiry: [Teleflows API documentation](https://docs.teleflows.io/getting-started/).
# Connect other apps
> Use the Teleflows MCP server from other MCP apps and IDEs.
Any app that supports remote MCP servers can connect.
1. Add the server address as a remote (HTTP) MCP server:
```plaintext
https://mcp.teleflows.io
```
2. Start the connection. Sign-in opens in your browser.
3. Check the sign-in page, then paste your [API key](/guides/mcp/how-to/create-api-key/) and select **Connect**.
Caution
An app marked **unverified app** on the sign-in page chose its own name. Continue only if you started the connection yourself and recognise the return address. See [Sign-in and security](/guides/mcp/concepts/sign-in-and-security/).
# Revoke access
> Disconnect an app, or revoke the API key to stop every connection that uses it.
## Disconnect one app
[Section titled “Disconnect one app”](#disconnect-one-app)
Remove or disconnect the Teleflows connector in your app’s settings.
## Stop all access at once
[Section titled “Stop all access at once”](#stop-all-access-at-once)
1. In Teleflows, open **Settings → API keys**.
2. Revoke the key.
Expired and revoked keys cannot make requests, so every connection that uses the key stops working.
Tip
If you use a separate key for each app, revoking one key stops only that app.
# Use these docs with AI
> Give these docs to an AI assistant or coding agent as Markdown, page by page or all at once.
These docs are also available as plain Markdown, so AI assistants and coding agents can read them without the website around them.
## Copy a page
[Section titled “Copy a page”](#copy-a-page)
At the top of each page, select **Copy page** to copy the page as Markdown. Then paste it into your assistant.
The menu next to it has more options:
* **View as Markdown**: opens the page as plain Markdown.
* **Open in Claude** or **Open in ChatGPT**: starts a chat that asks the assistant to read the page.
* **Open in Claude desktop**: opens the Claude desktop app with this page in a new prompt, ready for your question. It is not sent until you send it. Needs the installed app.
* **Open in Codex**: opens the Codex app with this page in a new prompt, ready for your question. It is not sent until you send it. Needs the installed app.
Long pages are passed to the desktop apps as a link to their Markdown copy instead of the full text.
## Get a page as Markdown
[Section titled “Get a page as Markdown”](#get-a-page-as-markdown)
Every page has a Markdown copy at its address with `.md` instead of the final slash:
| Page | Markdown |
| ------------------------------------------------------------- | --------------------------------------------------------------- |
| `https://docs.teleflows.io/guides/mcp/how-to/connect-claude/` | `https://docs.teleflows.io/guides/mcp/how-to/connect-claude.md` |
| `https://docs.teleflows.io/guides/` | `https://docs.teleflows.io/guides/index.md` |
Each copy starts with a short header: the title, its web address, the date it was last updated, the type of page, a one-sentence summary and related pages.
## Get all the docs at once
[Section titled “Get all the docs at once”](#get-all-the-docs-at-once)
| File | What it holds |
| ------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [`llms.txt`](https://docs.teleflows.io/llms.txt) | An index of every page, with links to the Markdown copies |
| [`llms-full.txt`](https://docs.teleflows.io/llms-full.txt) | All pages in one file |
| [`llms-small.txt`](https://docs.teleflows.io/llms-small.txt) | All pages in one file, shortened |
| [`openapi.json`](https://docs.teleflows.io/openapi.json) | The machine-readable description (OpenAPI 3.1) of the Teleflows Customer API that the server reads. People can browse it in the [Teleflows API reference](/api-reference/). |
## Tell your coding agent about Teleflows MCP
[Section titled “Tell your coding agent about Teleflows MCP”](#tell-your-coding-agent-about-teleflows-mcp)
Coding agents read project instructions from a file such as `AGENTS.md` or `CLAUDE.md`. Copy this block into it:
```markdown
## Teleflows MCP server
- Read-only MCP server for the Teleflows call-tracking API: it reads calls, call reports,
campaigns, publishers, buyers, routing and setup. It cannot create, change or delete
anything in Teleflows.
- Address: https://mcp.teleflows.io (remote MCP server over HTTP). Sign-in happens in the
browser with a Teleflows API key; the key's role decides what can be read.
- Claude Code: `claude mcp add --transport http teleflows https://mcp.teleflows.io`, then
run `/mcp` and sign in.
- Docs: https://docs.teleflows.io/llms.txt (index). Add `.md` to any docs page address
for Markdown, for example https://docs.teleflows.io/guides/mcp/reference/tools.md.
- Never put a Teleflows API key in code, config or chat; sign in through the browser.
```
Note
The Markdown copies hold the same content as the web pages. Screenshots are left out.
# Limits
> Time windows, page sizes, result size and time limits of the Teleflows MCP server.
## Time windows
[Section titled “Time windows”](#time-windows)
Tools that read calls or events by time use a window from `since` to `until`.
* A window is at most **31 days**. Longer windows are refused; ask for longer periods in parts.
* Without `since` and `until`, the window is the **last 24 hours**.
* All times are in **UTC**.
* A date without a time, such as `2026-09-30`, means **00:00 UTC** that day.
* `until` is **exclusive**. For a single day, use that day as `since` and the next day as `until`. For example, 30 September 2026 is `since 2026-09-30`, `until 2026-10-01`.
* A date-time needs a timezone, for example `2026-09-30T00:00:00Z` or `+05:00`.
## Page sizes
[Section titled “Page sizes”](#page-sizes)
Long lists come in pages. The assistant asks for the next page when it needs more.
| Tool | Per page | Default |
| ---------------------------- | -------- | ------- |
| List tools (`page_size`) | 1 to 100 | 20 |
| Search calls (`limit`) | 1 to 50 | 25 |
| Call report groups (`limit`) | 1 to 100 | 50 |
For counts and totals, the assistant uses the call report instead of paging through calls.
## Result size
[Section titled “Result size”](#result-size)
Each result is kept under about 45,000 characters, so it fits within the assistant’s limits. If a result is larger, whole items are left out from the end, the result is marked as truncated, and a note says how many were left out. Ask for a smaller page, fewer included parts or a narrower filter to see them.
## Time and reads per question
[Section titled “Time and reads per question”](#time-and-reads-per-question)
One tool call can take up to **45 seconds** and make up to **50 reads** from Teleflows. Larger requests stop with a message asking you to narrow them: fewer included parts, a smaller window or a more specific filter.
If Teleflows is busy, rate limiting or does not answer, the server may wait a few seconds and try once more. If that fails, it stops the rest of that request and says so.
## Data as Teleflows returns it
[Section titled “Data as Teleflows returns it”](#data-as-teleflows-returns-it)
Records are shown as Teleflows returns them. Money fields ending in `_cents` are in cents. Where Teleflows does not document what a value means, the assistant says so instead of guessing.
Exact inputs and limits for each tool: [Tools](/guides/mcp/reference/tools/).
# Messages
> Messages the Teleflows MCP server can show and what to do about each one.
The server’s messages are short and safe to show: they never contain your key. The assistant may repeat them in its own words.
## Sign-in page
[Section titled “Sign-in page”](#sign-in-page)
| Message | What it means | What to do |
| ------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| That does not look like a Teleflows API key (it starts with tfk\_). | The pasted text is not a Teleflows key. | Copy the whole key again from Teleflows. |
| Teleflows did not accept this key. Check that it is complete, active and not expired. | The key is incomplete, expired or revoked, or from another Teleflows environment. | Copy the whole key again, or [create a new one](/guides/mcp/how-to/create-api-key/). Check the [server address](/guides/mcp/concepts/server-address/). |
| The key could not be checked with Teleflows right now. Try again in a moment. | Teleflows did not answer the key check. | Try again in a moment. |
| Too many attempts for this sign-in. Start again from your app. | Several wrong keys in one sign-in. | Start the connection again from your app. |
| This sign-in has expired. Start again from your app. | The sign-in took too long or was already used. | Start the connection again from your app. |
| Finish the sign-in in the browser window that started it. Start again from your app. | The key was sent from a different browser or tab. | Start again from your app and finish in the window that opens. |
| Too many sign-in requests. Wait a minute and try again. | Many sign-ins in a short time. | Wait a minute and try again. |
| Too many sign-in attempts. Wait a minute and try again. | Many keys sent in a short time. | Wait a minute and try again. |
| This app is not registered with the Teleflows MCP server. | The app did not identify itself in a way the server accepts. | Start again from your app. If it persists, the app may not support this server. |
| The app’s return address is not registered for this app. | The app asked to return to an address it did not register. | Do not continue. Start again from your app. |
## Answers to questions
[Section titled “Answers to questions”](#answers-to-questions)
| Message | What it means | What to do |
| -------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------- |
| Your Teleflows API key is invalid, expired or revoked. Create a new key in Teleflows under Settings → API keys. | The key stopped working after you connected. | [Create a new key](/guides/mcp/how-to/create-api-key/) and connect again. |
| Your API key’s role cannot use this. Ask a Teleflows admin for a key with more access. | The key’s role cannot read this data. | Use a key with a role that can, or ask a Teleflows admin. See [Roles and access](/guides/mcp/concepts/roles-and-access/). |
| … not found, or not visible to your API key. | The record does not exist, or your key’s role cannot see it. | Check the name or ID, or use a key with more access. |
| No recording, or not visible to your API key. | The call has no recording, or your key’s role cannot see it. | Use a key with more access if you expect a recording. |
| Cost (`total_cost_cents`) is not available for your API key’s role. | Teleflows did not return the cost field for your key. | Nothing to do: the result shows the fields Teleflows returned. |
| The window is … days; the maximum is 31. … | The question covers more than 31 days. | Ask for the period in parts of up to 31 days. See [Limits](/guides/mcp/reference/limits/). |
| since must be before until. … | The start of the period is not before its end. | Ask again with a valid period. `until` is exclusive. |
| … item(s) were left out to fit the size limit. … | The result was too large and was shortened. | Ask for fewer records, fewer details or a narrower filter. |
| This request needed more Teleflows reads or time than one tool call allows. … | The question needed too much work at once. | Narrow it: fewer details, a smaller period or a more specific filter. |
| Teleflows is rate limiting requests. Wait a moment and try again. | Teleflows asked the server to slow down. | Wait a moment and try again. |
| Teleflows is temporarily unavailable. Try again later. | Teleflows is down or busy. | Try again later. |
| Teleflows did not answer in time. Try again later. | Teleflows took too long to answer. | Try again later, or ask a narrower question. |
| Could not connect to Teleflows. Try again later. | The server could not reach Teleflows. | Try again later. |
| Teleflows rejected the request: check the time window (at most 31 days, start before end) or start again without a cursor. | Teleflows refused the period or the page position. | Ask again with a valid period, or start the list from the beginning. |
| Invalid input. … Check the tool’s input schema. | The assistant sent an input the tool does not accept. | Usually the assistant corrects this itself. Otherwise rephrase the question. |
# Tools
> The read-only tools the Teleflows MCP server provides, grouped by area.
The Teleflows MCP server provides 28 tools. All of them only read data: none can create, change or delete anything in Teleflows. Your assistant chooses the tools for you; you ask in plain language.
| Tool | Name | Area |
| ----------------------------------------------------------------------------------------------------------------- | ------------------------------------ | ------------------------------------------------------------------------------------------- |
| [Search calls](/guides/mcp/reference/tools/calls-and-reports/#search-calls) | `teleflows_search_calls` | [Calls and reports](/guides/mcp/reference/tools/calls-and-reports/) |
| [Get call](/guides/mcp/reference/tools/calls-and-reports/#get-call) | `teleflows_get_call` | [Calls and reports](/guides/mcp/reference/tools/calls-and-reports/) |
| [Call report](/guides/mcp/reference/tools/calls-and-reports/#call-report) | `teleflows_get_call_report` | [Calls and reports](/guides/mcp/reference/tools/calls-and-reports/) |
| [Get call recording](/guides/mcp/reference/tools/calls-and-reports/#get-call-recording) | `teleflows_get_call_recording` | [Calls and reports](/guides/mcp/reference/tools/calls-and-reports/) |
| [List campaigns](/guides/mcp/reference/tools/campaigns-and-publishers/#list-campaigns) | `teleflows_list_campaigns` | [Campaigns and publishers](/guides/mcp/reference/tools/campaigns-and-publishers/) |
| [Get campaign](/guides/mcp/reference/tools/campaigns-and-publishers/#get-campaign) | `teleflows_get_campaign` | [Campaigns and publishers](/guides/mcp/reference/tools/campaigns-and-publishers/) |
| [List publishers](/guides/mcp/reference/tools/campaigns-and-publishers/#list-publishers) | `teleflows_list_publishers` | [Campaigns and publishers](/guides/mcp/reference/tools/campaigns-and-publishers/) |
| [Get publisher](/guides/mcp/reference/tools/campaigns-and-publishers/#get-publisher) | `teleflows_get_publisher` | [Campaigns and publishers](/guides/mcp/reference/tools/campaigns-and-publishers/) |
| [List tracking numbers](/guides/mcp/reference/tools/campaigns-and-publishers/#list-tracking-numbers) | `teleflows_list_tracking_numbers` | [Campaigns and publishers](/guides/mcp/reference/tools/campaigns-and-publishers/) |
| [List buyers](/guides/mcp/reference/tools/campaigns-and-publishers/#list-buyers) | `teleflows_list_buyers` | [Campaigns and publishers](/guides/mcp/reference/tools/campaigns-and-publishers/) |
| [List routing plans](/guides/mcp/reference/tools/routing-and-demand/#list-routing-plans) | `teleflows_list_routing_plans` | [Routing and demand](/guides/mcp/reference/tools/routing-and-demand/) |
| [Get routing plan](/guides/mcp/reference/tools/routing-and-demand/#get-routing-plan) | `teleflows_get_routing_plan` | [Routing and demand](/guides/mcp/reference/tools/routing-and-demand/) |
| [List targets](/guides/mcp/reference/tools/routing-and-demand/#list-targets) | `teleflows_list_targets` | [Routing and demand](/guides/mcp/reference/tools/routing-and-demand/) |
| [List target groups](/guides/mcp/reference/tools/routing-and-demand/#list-target-groups) | `teleflows_list_target_groups` | [Routing and demand](/guides/mcp/reference/tools/routing-and-demand/) |
| [List ring trees](/guides/mcp/reference/tools/routing-and-demand/#list-ring-trees) | `teleflows_list_ring_trees` | [Routing and demand](/guides/mcp/reference/tools/routing-and-demand/) |
| [List ring tree targets](/guides/mcp/reference/tools/routing-and-demand/#list-ring-tree-targets) | `teleflows_list_ring_tree_targets` | [Routing and demand](/guides/mcp/reference/tools/routing-and-demand/) |
| [Get ring tree target health](/guides/mcp/reference/tools/routing-and-demand/#get-ring-tree-target-health) | `teleflows_get_ring_tree_target` | [Routing and demand](/guides/mcp/reference/tools/routing-and-demand/) |
| [List workflows](/guides/mcp/reference/tools/call-flow-and-reporting-setup/#list-workflows) | `teleflows_list_workflows` | [Call-flow and reporting setup](/guides/mcp/reference/tools/call-flow-and-reporting-setup/) |
| [List variable definitions](/guides/mcp/reference/tools/call-flow-and-reporting-setup/#list-variable-definitions) | `teleflows_list_variables` | [Call-flow and reporting setup](/guides/mcp/reference/tools/call-flow-and-reporting-setup/) |
| [List audio files](/guides/mcp/reference/tools/call-flow-and-reporting-setup/#list-audio-files) | `teleflows_list_audio_files` | [Call-flow and reporting setup](/guides/mcp/reference/tools/call-flow-and-reporting-setup/) |
| [List blocked numbers](/guides/mcp/reference/tools/call-flow-and-reporting-setup/#list-blocked-numbers) | `teleflows_list_blocked_numbers` | [Call-flow and reporting setup](/guides/mcp/reference/tools/call-flow-and-reporting-setup/) |
| [List pixels](/guides/mcp/reference/tools/call-flow-and-reporting-setup/#list-pixels) | `teleflows_list_pixels` | [Call-flow and reporting setup](/guides/mcp/reference/tools/call-flow-and-reporting-setup/) |
| [List postback configs](/guides/mcp/reference/tools/call-flow-and-reporting-setup/#list-postback-configs) | `teleflows_list_postback_configs` | [Call-flow and reporting setup](/guides/mcp/reference/tools/call-flow-and-reporting-setup/) |
| [List predictive configs](/guides/mcp/reference/tools/call-flow-and-reporting-setup/#list-predictive-configs) | `teleflows_list_predictive_configs` | [Call-flow and reporting setup](/guides/mcp/reference/tools/call-flow-and-reporting-setup/) |
| [Get record by ID](/guides/mcp/reference/tools/general-and-monitoring/#get-record-by-id) | `teleflows_get_record` | [General and monitoring](/guides/mcp/reference/tools/general-and-monitoring/) |
| [Find where a record is used](/guides/mcp/reference/tools/general-and-monitoring/#find-where-a-record-is-used) | `teleflows_find_usages` | [General and monitoring](/guides/mcp/reference/tools/general-and-monitoring/) |
| [List conversion receipts](/guides/mcp/reference/tools/general-and-monitoring/#list-conversion-receipts) | `teleflows_list_conversion_receipts` | [General and monitoring](/guides/mcp/reference/tools/general-and-monitoring/) |
| [List pixel fires](/guides/mcp/reference/tools/general-and-monitoring/#list-pixel-fires) | `teleflows_list_pixel_fires` | [General and monitoring](/guides/mcp/reference/tools/general-and-monitoring/) |
# Call-flow and reporting setup
> Reference for the 7 call-flow and reporting setup tools of the Teleflows MCP server.
Each tool lists the inputs your assistant can send. You do not type these yourself: ask in plain language and the assistant fills them in.
## List workflows
[Section titled “List workflows”](#list-workflows)
Tool name: `teleflows_list_workflows`
Lists workflows your API key can access (name, description, active flag).
Use it to find a workflow by name and get its ID; campaigns using it: `teleflows_find_usages` or `teleflows_list_campaigns` with `workflow_id`. The steps inside a workflow are not available through the API, and a call does not record which workflow ran.
**Inputs**
| Input | Details | Description |
| ---------------- | -------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
| `is_active` | boolean | Only active or only inactive workflows. |
| `created_after` | string; up to 40 characters | Only records created at or after this moment (inclusive): date-time with timezone, e.g. 2026-10-01T00:00:00Z. |
| `created_before` | string; up to 40 characters | Only records created at or before this moment (inclusive): date-time with timezone, e.g. 2026-10-31T23:59:59Z. |
| `search` | string; up to 200 characters | Text to match; partial matches of 3 or more characters work. |
| `sort` | string; `newest_first`, `oldest_first`; default `newest_first` | Order by creation time. |
| `page` | integer; 1 to 100000; default `1` | Page number, from 1. |
| `page_size` | integer; 1 to 100; default `20` | Records per page, 1-100. |
## List variable definitions
[Section titled “List variable definitions”](#list-variable-definitions)
Tool name: `teleflows_list_variables`
Lists variable definitions your API key can access.
Definitions only: variable values are never returned by Teleflows. Use it to see which variables exist, which are marked secret or personal data (`is_secret`, `is_pii`), and where their values come from (source). There is no filter for `is_pii`: check it in the results.
**Inputs**
| Input | Details | Description |
| ----------- | ------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------ |
| `scope` | string; `system`, `organization`, `call`, `node`, `event` | Variable scope. |
| `source` | string; `platform`, `organization`, `ide`, `sip_header`, `dialer`, `gather`, `menu`, `api`, `profile`, `splitter`, `event`, `legacy` | Where values come from. |
| `status` | string; `active`, `deprecated`, `disabled` | Definition status. |
| `is_secret` | boolean | Only secret or only non-secret variables. |
| `search` | string; up to 200 characters | Text to match; partial matches of 3 or more characters work. |
| `sort` | string; `newest_first`, `oldest_first`; default `newest_first` | Order by creation time. |
| `page` | integer; 1 to 100000; default `1` | Page number, from 1. |
| `page_size` | integer; 1 to 100; default `20` | Records per page, 1-100. |
## List audio files
[Section titled “List audio files”](#list-audio-files)
Tool name: `teleflows_list_audio_files`
Lists audio files in the account (name, file type, size).
Use it to find an audio file by name. The audio itself and where a file is used are not available through the API.
**Inputs**
| Input | Details | Description |
| ----------- | -------------------------------------------------------------- | ------------------------------------------------------------ |
| `search` | string; up to 200 characters | Text to match; partial matches of 3 or more characters work. |
| `sort` | string; `newest_first`, `oldest_first`; default `newest_first` | Order by creation time. |
| `page` | integer; 1 to 100000; default `1` | Page number, from 1. |
| `page_size` | integer; 1 to 100; default `20` | Records per page, 1-100. |
## List blocked numbers
[Section titled “List blocked numbers”](#list-blocked-numbers)
Tool name: `teleflows_list_blocked_numbers`
Lists blocked numbers your API key can access.
value is a full phone number or a number prefix (`block_type` exact or prefix); `expires_at` may be null (no expiry date returned). To check whether a number is blocked, search for it and also consider prefix entries that match its start. How blocking is applied to calls is not documented. Blocked calls per period are counted in `teleflows_get_call_report` (blocked).
**Inputs**
| Input | Details | Description |
| ------------ | -------------------------------------------------------------- | ------------------------------------------------------------ |
| `block_type` | string; `exact`, `prefix` | Full number or prefix. |
| `search` | string; up to 200 characters | Text to match; partial matches of 3 or more characters work. |
| `sort` | string; `newest_first`, `oldest_first`; default `newest_first` | Order by creation time. |
| `page` | integer; 1 to 100000; default `1` | Page number, from 1. |
| `page_size` | integer; 1 to 100; default `20` | Records per page, 1-100. |
## List pixels
[Section titled “List pixels”](#list-pixels)
Tool name: `teleflows_list_pixels`
Lists tracking pixels (name, active flag).
For a pixel’s delivery results use `teleflows_list_pixel_fires`.
**Inputs**
| Input | Details | Description |
| ----------- | --------------------------------- | ------------------------ |
| `page` | integer; 1 to 100000; default `1` | Page number, from 1. |
| `page_size` | integer; 1 to 100; default `20` | Records per page, 1-100. |
## List postback configs
[Section titled “List postback configs”](#list-postback-configs)
Tool name: `teleflows_list_postback_configs`
Lists postback configurations your API key can access (name, active flag, authentication method, payload format, default event name, conversion window in days).
Endpoint URLs and credentials are not returned by Teleflows. Filter by `campaign_id` for one campaign’s postbacks.
**Inputs**
| Input | Details | Description |
| ------------- | -------------------------------------------------------------- | ------------------------------------------------------------ |
| `campaign_id` | string; 36 characters | The campaign ID (UUID). |
| `is_active` | boolean | Only active or only inactive configs. |
| `search` | string; up to 200 characters | Text to match; partial matches of 3 or more characters work. |
| `sort` | string; `newest_first`, `oldest_first`; default `newest_first` | Order by creation time. |
| `page` | integer; 1 to 100000; default `1` | Page number, from 1. |
| `page_size` | integer; 1 to 100; default `20` | Records per page, 1-100. |
## List predictive configs
[Section titled “List predictive configs”](#list-predictive-configs)
Tool name: `teleflows_list_predictive_configs`
Lists predictive routing configurations (name and settings).
What each setting means and what uses a configuration are not documented by Teleflows, so present the values without interpreting them.
**Inputs**
| Input | Details | Description |
| ----------- | --------------------------------- | ------------------------ |
| `page` | integer; 1 to 100000; default `1` | Page number, from 1. |
| `page_size` | integer; 1 to 100; default `20` | Records per page, 1-100. |
# Calls and reports
> Reference for the 4 calls and reports tools of the Teleflows MCP server.
Each tool lists the inputs your assistant can send. You do not type these yourself: ask in plain language and the assistant fills them in.
## Search calls
[Section titled “Search calls”](#search-calls)
Tool name: `teleflows_search_calls`
Lists individual calls your API key can access in a time window (at most 31 days, default the last 24 hours).
Use it to see or inspect specific calls: who called, which campaign, publisher, buyer and target, duration, status, recording and money. Do not use it to count or total calls: it returns no totals; use `teleflows_get_call_report` for counts, sums and breakdowns. Filter by campaign, buyer or publisher (IDs from the list tools) or by status; status live finds calls in progress that started within the window, so widen since for long calls. Results come in pages: pass `next_cursor` back to get the next page. Money fields are in cents and `total_cost_cents` is a string. Caller numbers may be masked and money fields missing if your key’s role does not allow them. The order of calls is not documented.
**Inputs**
| Input | Details | Description |
| -------------- | ------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `since` | string; up to 40 characters | Start of the window (inclusive): date-time with timezone, or YYYY-MM-DD meaning 00:00 UTC that day. Default: 24 hours before until. |
| `until` | string; up to 40 characters | End of the window (exclusive): date-time with timezone, or YYYY-MM-DD meaning 00:00 UTC that day, not included. Example: yesterday on 2026-10-01 is since 2026-09-30, until 2026-10-01. Default: now. At most 31 days after since; longer windows are rejected. |
| `campaign_id` | string; 36 characters | The campaign ID (UUID). |
| `buyer_id` | string; 36 characters | The buyer ID (UUID). |
| `publisher_id` | string; 36 characters | The publisher ID (UUID). |
| `status` | string; `live`, `connected`, `ended` | Call status. |
| `limit` | integer; 1 to 50; default `25` | Calls per page, 1-50 (larger pages would exceed client result limits). |
| `cursor` | string; up to 8192 characters | `next_cursor` from a previous result. Send it alone or with the same filters. |
## Get call
[Section titled “Get call”](#get-call)
Tool name: `teleflows_get_call`
Gets everything Teleflows returns about one call, by its `call_uuid` (from `teleflows_search_calls` or a report).
Use it to explain what happened on a call: status, timing, campaign, publisher, buyer, target, routing plan name, hang-up cause and money. Not for finding calls (use `teleflows_search_calls`) or totals (use `teleflows_get_call_report`). The result combines the call detail with the call’s row from the call list, because each carries fields the other lacks (for example `has_recording` and `end_call_source` only exist in the list row). Money is in cents; `total_cost_cents` is a string. Caller numbers may be masked and money fields missing, depending on your key’s role. Conversion details have come back empty in testing even for calls marked `has_conversion`, so an empty conversions list does not prove there was no conversion. Which workflow ran on a call is not recorded by Teleflows.
**Inputs**
| Input | Details | Description |
| --------- | ------------------------------- | ----------------------------------------------- |
| `call_id` | string; required; 36 characters | The call’s `call_uuid` (not `inbound_call_id`). |
## Call report
[Section titled “Call report”](#call-report)
Tool name: `teleflows_get_call_report`
Totals, breakdowns and trends for calls in a time window (at most 31 days, default the last 24 hours, UTC).
Use it for any “how many / how much / which is best” question: calls, connections, conversions, revenue, payout, profit, duplicates, blocked calls, average and total call length. totals covers the whole window; groups has one row per campaign, target, publisher, buyer, tracking number, state, date or duplicate flag (`group_by`), each with every metric; totals and groups also count blocked, duplicate, live, no-connect and IVR hang-up calls; rows grouped by tracking number, state, date or duplicate have no ID to look up; timeline shows one metric (metric) over time in buckets (bucket). For a daily table with all metrics use `group_by`=date. Filters: campaign, buyer, publisher (IDs from the list tools) and call status; there is no target or tracking-number filter. Rates are calculated by Teleflows: `conversion_pct` = converted / incoming × 100; `margin_pct` = `profit_net_cents` / `revenue_cents` × 100; `rpc_cents` = `revenue_cents` / incoming; `acl_seconds` = average connected length. Money is in cents; `total_cost_cents` is a string. Money metrics need financial permissions: a 0 can mean either zero or hidden for your key’s role. Windows longer than 31 days are rejected: for longer periods, request several windows; add counts and cents, but do not add or average the rates across windows. If there are more groups, pass `next_cursor`; totals and timeline come from the first page.
**Inputs**
| Input | Details | Description |
| -------------- | ------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `since` | string; up to 40 characters | Start of the window (inclusive): date-time with timezone, or YYYY-MM-DD meaning 00:00 UTC that day. Default: 24 hours before until. |
| `until` | string; up to 40 characters | End of the window (exclusive): date-time with timezone, or YYYY-MM-DD meaning 00:00 UTC that day, not included. Example: yesterday on 2026-10-01 is since 2026-09-30, until 2026-10-01. Default: now. At most 31 days after since; longer windows are rejected. |
| `group_by` | string; `campaign`, `target`, `publisher`, `buyer`, `tracking_number`, `state`, `date`, `duplicate`; default `campaign` | One row per value of this dimension. |
| `metric` | string; `incoming`, `completed`, `connected`, `paid`, `converted`, `revenue`, `profit`, `tcl`, `acl`; default `incoming` | Metric for the timeline only; group rows carry every metric. |
| `bucket` | string; `minute`, `hour`, `day`, `week`, `month`; default `day` | Timeline bucket size (UTC). |
| `campaign_id` | string; 36 characters | The campaign ID (UUID). |
| `buyer_id` | string; 36 characters | The buyer ID (UUID). |
| `publisher_id` | string; 36 characters | The publisher ID (UUID). |
| `status` | string; `live`, `connected`, `ended` | Call status. |
| `limit` | integer; 1 to 100; default `50` | Groups per page, 1-100. |
| `cursor` | string; up to 8192 characters | `next_cursor` from a previous result. Send it alone or with the same filters. |
## Get call recording
[Section titled “Get call recording”](#get-call-recording)
Tool name: `teleflows_get_call_recording`
Checks whether a call’s recording can be downloaded and, only when asked, returns a short-lived download link (valid about 10 minutes).
Set `include_link` to true only when the user explicitly asks for the link. The link is a credential: it works only together with the same Teleflows API key (a browser cannot open it on its own), and it must not be shared. To see whether a call has a recording at all, `has_recording` is in `teleflows_get_call` or `teleflows_search_calls`. Audio itself is not returned.
**Inputs**
| Input | Details | Description |
| -------------- | ------------------------------- | -------------------------------------------------------------------------------- |
| `call_id` | string; required; 36 characters | The call’s `call_uuid`. |
| `include_link` | boolean; default `false` | Return the short-lived download link. Only when the user explicitly asks for it. |
# Campaigns and publishers
> Reference for the 6 campaigns and publishers tools of the Teleflows MCP server.
Each tool lists the inputs your assistant can send. You do not type these yourself: ask in plain language and the assistant fills them in.
## List campaigns
[Section titled “List campaigns”](#list-campaigns)
Tool name: `teleflows_list_campaigns`
Lists campaigns your API key can access.
Use it to find a campaign by name, get its ID for other tools, count campaigns by status (pagination.total), or find campaigns that use a given routing plan, workflow or publisher (filters take IDs from the matching list tools). A campaign record holds only its name, country, status, open-to-publishers flag and dates; for payout tiers, publishers, routing plan or workflow use `teleflows_get_campaign`.
**Inputs**
| Input | Details | Description |
| ----------------- | -------------------------------------------------------------- | ------------------------------------------------------------------- |
| `status` | string; `draft`, `active`, `paused`, `archived` | Campaign status. |
| `publisher_id` | string; 36 characters | The publisher ID (UUID). |
| `routing_plan_id` | string; 36 characters | The routing plan ID (UUID). |
| `workflow_id` | string; 36 characters | The workflow ID (UUID). |
| `unlinked` | boolean; `true` | Only true is supported; its meaning is not documented by Teleflows. |
| `search` | string; up to 200 characters | Text to match; partial matches of 3 or more characters work. |
| `sort` | string; `newest_first`, `oldest_first`; default `newest_first` | Order by creation time. |
| `page` | integer; 1 to 100000; default `1` | Page number, from 1. |
| `page_size` | integer; 1 to 100; default `20` | Records per page, 1-100. |
## Get campaign
[Section titled “Get campaign”](#get-campaign)
Tool name: `teleflows_get_campaign`
Gets one campaign by ID, optionally with its payout tiers, member publishers, routing plan and workflow (include).
Use it for “show me campaign X and how it pays / who sends traffic / how it routes”. Payout tiers: amounts in cents, `rev_share_pct` is a string, Teleflows evaluates tiers in priority order; which tier a specific call matched is not available. Publishers: membership records with publisher IDs; names are added by this server. Routing plan and workflow are not stored on the campaign; this server finds them by checking which routing plan and workflow list the campaign, and says so. Tracking numbers: use `teleflows_list_tracking_numbers` with `campaign_id`.
**Inputs**
| Input | Details | Description |
| ----------------- | --------------------------------------------------------------- | ----------------------------------------------------------- |
| `campaign_id` | string; required; 36 characters | The campaign ID (UUID). |
| `include` | array; `payout_tiers`, `publishers`, `routing_plan`, `workflow` | Related data to add; each part is fetched only when listed. |
| `tiers_page` | integer; 1 to 100000; default `1` | Page number, from 1. |
| `publishers_page` | integer; 1 to 100000; default `1` | Page number, from 1. |
## List publishers
[Section titled “List publishers”](#list-publishers)
Tool name: `teleflows_list_publishers`
Lists publishers your API key can access (name, sub ID, active flag, timezone).
Use it to find a publisher by name and get its ID for other tools. For one publisher’s campaigns or SIP connection use `teleflows_get_publisher`. There is no filter for active publishers: check `is_active` in the results.
**Inputs**
| Input | Details | Description |
| ----------- | -------------------------------------------------------------- | ------------------------------------------------------------ |
| `search` | string; up to 200 characters | Text to match; partial matches of 3 or more characters work. |
| `sort` | string; `newest_first`, `oldest_first`; default `newest_first` | Order by creation time. |
| `page` | integer; 1 to 100000; default `1` | Page number, from 1. |
| `page_size` | integer; 1 to 100; default `20` | Records per page, 1-100. |
## Get publisher
[Section titled “Get publisher”](#get-publisher)
Tool name: `teleflows_get_publisher`
Gets one publisher by ID, optionally with the campaigns it belongs to, its SIP connection status and its SIP event history (include).
SIP status is the saved state; reading it does not trigger a connection check, and SIP usernames and passwords are never returned. SIP history is paged, without a time filter; its order is not documented. For campaigns of a publisher, `teleflows_list_campaigns` with `publisher_id` gives full campaign records.
**Inputs**
| Input | Details | Description |
| ------------------- | ------------------------------------------------ | ----------------------------------------------------------- |
| `publisher_id` | string; required; 36 characters | The publisher ID (UUID). |
| `include` | array; `campaigns`, `sip_status`, `sip_activity` | Related data to add; each part is fetched only when listed. |
| `campaigns_page` | integer; 1 to 100000; default `1` | Page number, from 1. |
| `sip_activity_page` | integer; 1 to 100000; default `1` | Page number, from 1. |
## List tracking numbers
[Section titled “List tracking numbers”](#list-tracking-numbers)
Tool name: `teleflows_list_tracking_numbers`
Lists tracking numbers your API key can access.
Use it for “which numbers belong to campaign X”, “how many active US numbers do we have” (pagination.total with `page_size` 1), or to find a number. A tracking number record has no campaign or publisher field, so filtering is the only way to link them; to find the campaign of one number, filter by each campaign or look at a call to that number. Status values: active, pending, releasing, deleted (their meanings are not documented).
**Inputs**
| Input | Details | Description |
| ---------------- | -------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
| `campaign_id` | string; 36 characters | The campaign ID (UUID). |
| `publisher_id` | string; 36 characters | The publisher ID (UUID). |
| `status` | string; `active`, `pending`, `releasing`, `deleted` | Number status. |
| `country` | string; 2 characters | Two-letter country code, e.g. US. |
| `created_after` | string; up to 40 characters | Only records created at or after this moment (inclusive): date-time with timezone, e.g. 2026-10-01T00:00:00Z. |
| `created_before` | string; up to 40 characters | Only records created at or before this moment (inclusive): date-time with timezone, e.g. 2026-10-31T23:59:59Z. |
| `search` | string; up to 200 characters | Text to match; partial matches of 3 or more characters work. |
| `sort` | string; `newest_first`, `oldest_first`; default `newest_first` | Order by creation time. |
| `page` | integer; 1 to 100000; default `1` | Page number, from 1. |
| `page_size` | integer; 1 to 100; default `20` | Records per page, 1-100. |
## List buyers
[Section titled “List buyers”](#list-buyers)
Tool name: `teleflows_list_buyers`
Lists the buyers in the Teleflows account that your API key can access, with each buyer’s company name, sub ID, timezone, active flag and hourly, daily, monthly and concurrency caps.
Use it to find a buyer by company name, to get a buyer’s ID for other tools (for example to filter calls by buyer), or to count buyers (pagination.total). Search matches company names; partial names of 3 or more characters work. Results come newest first by default, 20 per page (up to 100); use page to get more. Records are returned exactly as Teleflows sends them. Caps may be null or -1; Teleflows does not document what either means for buyers, or what counts toward a cap, so do not state that they mean unlimited.
**Inputs**
| Input | Details | Description |
| ----------- | -------------------------------------------------------------- | --------------------------------------------------------- |
| `search` | string; up to 200 characters | Part of a company name to match. Omit to list all buyers. |
| `sort` | string; `newest_first`, `oldest_first`; default `newest_first` | Order by creation time. |
| `page` | integer; 1 to 100000; default `1` | Page number, from 1. |
| `page_size` | integer; 1 to 100; default `20` | Buyers per page, 1-100. |
# General and monitoring
> Reference for the 4 general and monitoring tools of the Teleflows MCP server.
Each tool lists the inputs your assistant can send. You do not type these yourself: ask in plain language and the assistant fills them in.
## Get record by ID
[Section titled “Get record by ID”](#get-record-by-id)
Tool name: `teleflows_get_record`
Gets one record by type and ID, when you already have the ID (for example `buyer_id` or `target_id` from a call, or an ID from a list).
Ring trees and target groups include their members (ID, name, position). Campaigns, publishers, routing plans and ring tree targets have their own tools with more detail: `teleflows_get_campaign`, `teleflows_get_publisher`, `teleflows_get_routing_plan`, `teleflows_get_ring_tree_target`. A call’s `target_id` can point to a target or to a ring tree target: if target returns not found, try `teleflows_get_ring_tree_target`. Ring tree members are ring tree targets; what target group members point to is not documented.
**Inputs**
| Input | Details | Description |
| ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------- |
| `record_type` | string; required; `buyer`, `target`, `ring_tree`, `target_group`, `tracking_number`, `workflow`, `variable`, `audio_file`, `blocked_number`, `pixel`, `postback_config`, `predictive_config` | What kind of record. |
| `id` | string; required; 36 characters | A Teleflows ID (UUID). |
## Find where a record is used
[Section titled “Find where a record is used”](#find-where-a-record-is-used)
Tool name: `teleflows_find_usages`
Shows where a workflow, routing plan, target, target group, ring tree or ring tree target is used: the records that reference it (for example the campaigns using a routing plan, or the routes pointing at a target).
Use it for “what breaks if I change or disable X”. Route references are resolved to their routing plans by this server, because Teleflows does not return the plan. Only records your API key can access are included. Buyers, publishers, campaigns, numbers, pixels, postbacks, variables, audio files and predictive configs have no usage lookup: for a publisher’s campaigns use `teleflows_list_campaigns` with `publisher_id`; for a campaign’s numbers or postbacks use `teleflows_list_tracking_numbers` or `teleflows_list_postback_configs` with `campaign_id`.
**Inputs**
| Input | Details | Description |
| ------------- | ------------------------------------------------------------------------------------------------------- | ---------------------- |
| `record_type` | string; required; `workflow`, `routing_plan`, `target`, `target_group`, `ring_tree`, `ring_tree_target` | What kind of record. |
| `id` | string; required; 36 characters | A Teleflows ID (UUID). |
| `page` | integer; 1 to 100000; default `1` | Page number, from 1. |
## List conversion receipts
[Section titled “List conversion receipts”](#list-conversion-receipts)
Tool name: `teleflows_list_conversion_receipts`
Lists conversion processing receipts in a time window: when each was received, its processing status, latency and test flag.
Use it to monitor whether conversions are being processed and how fast. Receipts cannot be linked to a specific call or campaign in the API. There is no status filter: count statuses in the results. The window end is sent as given; whether Teleflows includes a record at exactly that moment is not documented.
**Inputs**
| Input | Details | Description |
| ----------- | --------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `since` | string; up to 40 characters | Start of the window (inclusive): date-time with timezone, or YYYY-MM-DD meaning 00:00 UTC that day. Default: 24 hours before until. |
| `until` | string; up to 40 characters | End of the window (exclusive): date-time with timezone, or YYYY-MM-DD meaning 00:00 UTC that day, not included. Example: yesterday on 2026-10-01 is since 2026-09-30, until 2026-10-01. Default: now. At most 31 days after since; longer windows are rejected. |
| `page` | integer; 1 to 100000; default `1` | Page number, from 1. |
| `page_size` | integer; 1 to 100; default `20` | Records per page, 1-100. |
## List pixel fires
[Section titled “List pixel fires”](#list-pixel-fires)
Tool name: `teleflows_list_pixel_fires`
Lists one pixel’s delivery results in a time window: trigger event, status, the response code and latency from the receiving side, test flag and attempt number.
Reads saved results only: it never fires a pixel, and request contents are not available. Pixel fires cannot be linked to a specific call in the API. For all pixels, list them with `teleflows_list_pixels` and check each.
**Inputs**
| Input | Details | Description |
| ----------- | --------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `pixel_id` | string; required; 36 characters | The pixel ID (UUID). |
| `since` | string; up to 40 characters | Start of the window (inclusive): date-time with timezone, or YYYY-MM-DD meaning 00:00 UTC that day. Default: 24 hours before until. |
| `until` | string; up to 40 characters | End of the window (exclusive): date-time with timezone, or YYYY-MM-DD meaning 00:00 UTC that day, not included. Example: yesterday on 2026-10-01 is since 2026-09-30, until 2026-10-01. Default: now. At most 31 days after since; longer windows are rejected. |
| `page` | integer; 1 to 100000; default `1` | Page number, from 1. |
| `page_size` | integer; 1 to 100; default `20` | Records per page, 1-100. |
# Routing and demand
> Reference for the 7 routing and demand tools of the Teleflows MCP server.
Each tool lists the inputs your assistant can send. You do not type these yourself: ask in plain language and the assistant fills them in.
## List routing plans
[Section titled “List routing plans”](#list-routing-plans)
Tool name: `teleflows_list_routing_plans`
Lists routing plans your API key can access (name and routing mode).
Use it to find a plan by name and get its ID. For a plan’s routes use `teleflows_get_routing_plan`; for the campaigns that use a plan use `teleflows_find_usages` or `teleflows_list_campaigns` with `routing_plan_id`.
**Inputs**
| Input | Details | Description |
| ----------- | -------------------------------------------------------------- | ------------------------------------------------------------ |
| `search` | string; up to 200 characters | Text to match; partial matches of 3 or more characters work. |
| `sort` | string; `newest_first`, `oldest_first`; default `newest_first` | Order by creation time. |
| `page` | integer; 1 to 100000; default `1` | Page number, from 1. |
| `page_size` | integer; 1 to 100; default `20` | Records per page, 1-100. |
## Get routing plan
[Section titled “Get routing plan”](#get-routing-plan)
Tool name: `teleflows_get_routing_plan`
Gets one routing plan by ID, optionally with its routes (include).
Each route has a type, priority, weight, concurrency cap and duplicate settings (`dedup_seconds`, `on_duplicate`). Teleflows does not return where a route sends calls: routes carry settings only. To see which routes use a target, ring tree or target group, use `teleflows_find_usages` on that target, ring tree or group. How priority and weight are applied is not documented by Teleflows.
**Inputs**
| Input | Details | Description |
| ------------- | --------------------------------- | ----------------------------------------------------------- |
| `plan_id` | string; required; 36 characters | The routing plan ID (UUID). |
| `include` | array; `routes` | Related data to add; each part is fetched only when listed. |
| `routes_page` | integer; 1 to 100000; default `1` | Page number, from 1. |
## List targets
[Section titled “List targets”](#list-targets)
Tool name: `teleflows_list_targets`
Lists targets (call destinations) your API key can access: name, destination (a phone number or SIP address), type, active flag, timezone, connection timeout and caps.
Use it to find a target by name, list active SIP targets, or those with a health check. A target record has no buyer field; `buyer_id` and `has_buyer` filters are the only link to buyers. Only the `has_health_check` flag exists: live health results for targets are not available. Caps may be null or -1; their meaning is not documented for targets.
**Inputs**
| Input | Details | Description |
| ------------------ | -------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
| `is_active` | boolean | Only active or only inactive targets. |
| `destination_type` | string; `number`, `sip` | Destination kind. |
| `has_health_check` | boolean | Only targets with or without a health check. |
| `has_buyer` | boolean | Only targets with or without a buyer. |
| `buyer_id` | string; 36 characters | The buyer ID (UUID). |
| `created_after` | string; up to 40 characters | Only records created at or after this moment (inclusive): date-time with timezone, e.g. 2026-10-01T00:00:00Z. |
| `created_before` | string; up to 40 characters | Only records created at or before this moment (inclusive): date-time with timezone, e.g. 2026-10-31T23:59:59Z. |
| `search` | string; up to 200 characters | Text to match; partial matches of 3 or more characters work. |
| `sort` | string; `newest_first`, `oldest_first`; default `newest_first` | Order by creation time. |
| `page` | integer; 1 to 100000; default `1` | Page number, from 1. |
| `page_size` | integer; 1 to 100; default `20` | Records per page, 1-100. |
## List target groups
[Section titled “List target groups”](#list-target-groups)
Tool name: `teleflows_list_target_groups`
Lists target groups your API key can access (name, active flag, simultaneous-dial flag, timezone, caps).
Use it to find a group by name. For a group’s members use `teleflows_get_record` with `record_type` `target_group`; for where it is used use `teleflows_find_usages`.
**Inputs**
| Input | Details | Description |
| ----------- | -------------------------------------------------------------- | ------------------------------------------------------------ |
| `search` | string; up to 200 characters | Text to match; partial matches of 3 or more characters work. |
| `sort` | string; `newest_first`, `oldest_first`; default `newest_first` | Order by creation time. |
| `page` | integer; 1 to 100000; default `1` | Page number, from 1. |
| `page_size` | integer; 1 to 100; default `20` | Records per page, 1-100. |
## List ring trees
[Section titled “List ring trees”](#list-ring-trees)
Tool name: `teleflows_list_ring_trees`
Lists ring trees your API key can access (name, timezone, dial timeout, ping timeout).
Use it to find a ring tree by name. For its members use `teleflows_get_record` with `record_type` `ring_tree`; for where it is used use `teleflows_find_usages`.
**Inputs**
| Input | Details | Description |
| ----------- | -------------------------------------------------------------- | ------------------------------------------------------------ |
| `search` | string; up to 200 characters | Text to match; partial matches of 3 or more characters work. |
| `sort` | string; `newest_first`, `oldest_first`; default `newest_first` | Order by creation time. |
| `page` | integer; 1 to 100000; default `1` | Page number, from 1. |
| `page_size` | integer; 1 to 100; default `20` | Records per page, 1-100. |
## List ring tree targets
[Section titled “List ring tree targets”](#list-ring-tree-targets)
Tool name: `teleflows_list_ring_tree_targets`
Lists ring tree targets your API key can access (name, display ID, status).
Use it to find one by name before checking its health with `teleflows_get_ring_tree_target`. The buyer and revenue-trigger filters refer to data not shown in the results, so their effect cannot be checked from the list.
**Inputs**
| Input | Details | Description |
| ----------------- | ---------------------------------------------------------------- | ------------------------------------------------------------ |
| `buyer_id` | string; 36 characters | The buyer ID (UUID). |
| `has_buyer` | boolean | Only with or without a buyer. |
| `revenue_trigger` | string; `CONNECTED`, `CALL_LENGTH`, `DIALED`, `POSTBACK_WEBHOOK` | Revenue trigger. |
| `search` | string; up to 200 characters | Text to match; partial matches of 3 or more characters work. |
| `sort` | string; `newest_first`, `oldest_first`; default `newest_first` | Order by creation time. |
| `page` | integer; 1 to 100000; default `1` | Page number, from 1. |
| `page_size` | integer; 1 to 100; default `20` | Records per page, 1-100. |
## Get ring tree target health
[Section titled “Get ring tree target health”](#get-ring-tree-target-health)
Tool name: `teleflows_get_ring_tree_target`
Gets one ring tree target by ID with its health: cap usage (used vs maximum per concurrency, hour, day and month; a maximum of -1 means unlimited), ping latency (median and 95th percentile) and saved ping results in a time window (default the last 24 hours, at most 31 days).
Use it for “is this target near its cap / slow / failing pings”. It reads saved results only and never sends a ping. Raw ping request and response bodies are not available. Which ring trees use this target: `teleflows_find_usages`.
**Inputs**
| Input | Details | Description |
| --------------------- | -------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ring_tree_target_id` | string; required; 36 characters | The ring tree target ID (UUID). |
| `include` | array; `cap_usage`, `latency`, `pings` | Parts to return; default: all. |
| `since` | string; up to 40 characters | Start of the window (inclusive): date-time with timezone, or YYYY-MM-DD meaning 00:00 UTC that day. Default: 24 hours before until. |
| `until` | string; up to 40 characters | End of the window (exclusive): date-time with timezone, or YYYY-MM-DD meaning 00:00 UTC that day, not included. Example: yesterday on 2026-10-01 is since 2026-09-30, until 2026-10-01. Default: now. At most 31 days after since; longer windows are rejected. |
| `pings_page` | integer; 1 to 100000; default `1` | Page number, from 1. |
| `ping_id` | string; 36 characters | Fetch one saved ping by ID; include and the time window are not needed with it. |
# Troubleshooting
> Fix common problems when connecting to the Teleflows MCP server or asking questions.
| You see | Why | What to do |
| --------------------------------------------------------------- | --------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
| Claude says “wasn’t connected” right after signing in | The page shows an earlier status; the sign-in itself completed. | Reload the page. The connector is usually already connected. |
| “Teleflows did not accept this key” | The key is incomplete, expired or revoked. | Copy the whole key again, or [create a new one](/guides/mcp/how-to/create-api-key/). |
| “Teleflows did not accept this key” with a key you just created | The key is from another Teleflows environment. | Use a key from the Teleflows environment the server reads. See [Server address](/guides/mcp/concepts/server-address/). |
| “Too many attempts for this sign-in” | Several wrong keys in one sign-in. | Start the connection again from your app. |
| “Your API key’s role cannot use this” | The key’s role cannot read that data. | Use a key with a role that can, or ask a Teleflows admin. |
| An empty answer | No records in that period, or the role cannot see them. | Try another period, or check with a key that has more access. |
| The assistant stops working after some weeks | The key expired, or the connection reached 90 days. | Connect again. Create a new key if it expired. |
Every message and what it means: [Messages](/guides/mcp/reference/messages/).
# What's new
> Changes to the Teleflows MCP server that you notice as a user, newest first.
## Open pages in the desktop apps (2026-10-02)
[Section titled “Open pages in the desktop apps (2026-10-02)”](#open-pages-in-the-desktop-apps-2026-10-02)
* The **Copy page** menu can open the Claude desktop app or Codex with the page in a new prompt.
## Teleflows API reference (2026-10-02)
[Section titled “Teleflows API reference (2026-10-02)”](#teleflows-api-reference-2026-10-02)
* The [Teleflows API reference](/api-reference/) shows every endpoint of the Teleflows Customer API that the server reads, with its OpenAPI file.
## Docs for AI tools (2026-10-02)
[Section titled “Docs for AI tools (2026-10-02)”](#docs-for-ai-tools-2026-10-02)
* Every page is available as Markdown, and a **Copy page** button copies it or opens it in Claude or ChatGPT. See [Use these docs with AI](/guides/mcp/how-to/use-docs-with-ai/).
## User documentation (2026-10-01)
[Section titled “User documentation (2026-10-01)”](#user-documentation-2026-10-01)
* User documentation for the Teleflows MCP server, with search. The server’s old `/guide` page now opens it.
## 0.5.0 (2026-10-01)
[Section titled “0.5.0 (2026-10-01)”](#050-2026-10-01)
* New server address: `https://mcp.teleflows.io`. The former address redirects there. Existing connections reconnect once.
## 0.4 (2026-10-01)
[Section titled “0.4 (2026-10-01)”](#04-2026-10-01)
* A user guide on the server.
* A refreshed look for the home, sign-in and error pages, with automatic dark mode.
* Signing in from several tabs in one browser works.
## 0.3 (2026-10-01)
[Section titled “0.3 (2026-10-01)”](#03-2026-10-01)
* Production launch.
* The sign-in page masks your key, and browsers no longer offer to save it as a password.
* A sign-in in progress survives a server update.
## 0.2.0 (2026-10-01)
[Section titled “0.2.0 (2026-10-01)”](#020-2026-10-01)
* ChatGPT support.
* The Teleflows logo on the sign-in page and in apps that show it.
* Clearer messages when an input is invalid or a recording is not available for your role.