BotpressComing soon
Let a Botpress bot answer with live web data. The SpecStream integration reads a request in plain words, shows the price, runs it once the user agrees, and returns rows with the page each value was read from.
SpecStream for BotpressAgent frameworks & builders
Until the Hub page opens, a bot that can send HTTPS requests can ask for the same data through the REST API: read the request, get a quote, start the run after the user agrees, and read the rows. Authenticate with your API key as a Bearer token.
What you need
- A Botpress workspace with a bot.
- A SpecStream account. New accounts start with $10 of work to use within 30 days, no card needed.
- A SpecStream API key for the bot, with a spending limit.
- 1
1. Add SpecStream from the Hub
Find SpecStream on the Botpress Hub and install it in the bot that needs live web data. You connect your account in the next step.
- 2
2. Connect your SpecStream account
Open Agents & API in SpecStream, switch to API keys and click Create API key. Label the key for this bot and keep the permissions that are already on. The integration needs Authorize paid work to start a run.
Click Set a total limit and enter the most the bot may ever spend through this key. Keys expire after 30 days by default, so set Expires after, days to cover how long the bot will stay live. SpecStream shows the key once, so copy it from the next screen.
In Botpress, open the integration's configuration and paste the key into API key. Set Most one list may cost (USD) to the largest price the bot may approve in one run. The default is 5. When the integration registers, it tries the key with SpecStream and stops with an error if SpecStream doesn't accept it.
- 3
3. Get a price
Add the Get a price action to a workflow. Fill Request with what the user wants, in plain words, including the place and the details to bring back. Set Rows to how many results to price. It defaults to 25 and goes up to 10,000. For example: "Roofing contractors in Columbus, Ohio rated 4.5 or higher, with phone and website".
The action returns Reading, which is how SpecStream understood the request. It returns Price, the most the run can cost, such as "$2.50". It also returns Quote ID, Quote hash, Most it can cost (cents), and Expires at. Nothing has run and nothing has been charged. Show the user the reading and the price. The price stays good for 30 minutes.
If the request is too vague to price, the action fails with a note on what to add, usually the place.
- 4
4. Approve and run after a yes
Ask the user whether to go ahead. For example: "Roofing contractors in Columbus rated 4.5 or higher, 25 rows, up to $2.50. Go ahead?" Run Approve and run only after they say yes.
Fill Quote ID and Quote hash from the price, and set Approved price (cents) to Most it can cost (cents). The action returns Find ID and State, which reads running once the run has started. SpecStream never charges more than the approved price, and approving the same quote twice doesn't charge twice. When the approved price is above Most one list may cost (USD), the action fails and nothing runs.
- 5
5. Read the rows
Add Get rows and pass Find ID. Set Rows per read, which is 25 by default and goes up to 100, and leave Cursor empty the first time. Reading costs nothing.
The action returns Status, Results so far, Rows, and Next cursor. A run takes from a few seconds to a few minutes. While Status reads running, call Get rows again a little later. The rows found so far are already there. When Next cursor has a value, pass it back as Cursor to read the next rows. It is empty when none are left.
What each row holds
Each item in Rows has an id and a list of cells. The columns follow the request, so a request for roofers with a phone number returns the business and the phone number. Every cell has these parts:
- Field: the column, such as "Business" or "Website".
- Value: the value as shown. It is empty when the web had no value.
- Source: the page the value was read from.
Price limits
Most one list may cost (USD) caps each run and lives in the integration. The key's total limit caps everything the bot spends through that key and lives in SpecStream. You pay only for rows that match, up to the price the user approved.
What a request covers
- Each request describes one kind of thing, such as roofers in one city. For a different set, get a new price.
- A price stays good for 30 minutes. After that, ask for a new one.
- Every run also appears in your SpecStream workspace, where you can open it, export it, or keep it current.
If an action fails
| What you see | What to do |
|---|---|
| SpecStream did not accept this API key | Create a new key under Agents & API and paste it into API key. A key past its expiry date is rejected. |
| SpecStream needs a clearer request | Add the place or the details you want back, then ask for a new price. |
| This costs up to $X, above this bot's limit of $Y | Raise Most one list may cost (USD) in the integration settings, or ask for fewer Rows. |
| This would go over the account's or the API key's spending limit | A limit on the key or the account has been reached. Raise the key's total limit under Agents & API, or write to [email protected]. |
| Add balance to continue | The balance falls short of the approved price. Add balance, then approve again. |
Cost
The integration is free. Each run is paid from your SpecStream balance at the price Get a price showed, and only for rows that match. Get rows costs nothing. Balance, quotes and billing explains how a price becomes a charge.
Remove
Remove the integration from the bot in Botpress. Delete the key under Agents & API in SpecStream if you want it to stop working for good. Runs you already started stay in your workspace. If a step here doesn't match what you see, write to [email protected]. The rest of the tools SpecStream connects to are in Connect your tools.
More
SpecStream for Botpress covers what it does in Botpress on one page. Every other tool has its guide in Connect your tools. You see the most a request can cost before it starts, and only the matches come out of your balance. Billing has the details. For help, email [email protected].