Send the words from your speech-to-text. Bell sends its guesses at each turn's words before the speaker finishes, then the end of the turn.
Bell is a model behind Rabel's API that learns each of your agents' own callers. It runs on Rabel's servers: there is nothing to host and no GPU. It answers in about 30 to 40 ms, while the caller is still talking, so it adds nothing to your pipeline's wait. One key holds up to 50 conversations at once.
The Rabel API is in beta. The launch price: the first 10,000 minutes are free, then $5 for every 10,000 minutes. An account opened at the launch price keeps it for 12 months from sign-up.
Base address: https://api.rabellabs.com
Sign up with your email:
curl -X POST https://api.rabellabs.com/v1/signup -H "Content-Type: application/json" -d '{"email": "you@example.com"}'
It answers status 202, and one email comes with a link. Open the link: it answers {"email": "...", "key": "rabel_..."}. The key is shown
once; keep it. The link works once and expires in 24 hours. Signing up again with the same email gives a new key and turns the old one
off; your use stays with your email.
Or continue with Google: the Continue with Google button on the sign up page opens GET /v1/login/google in your browser. After
Google's sign-in, an email with no account goes to the account page, which shows the key once, as the email's link does; an email
that has an account is signed in instead. Your Google account's email is your account's email; nothing else of the Google account is
kept.
Set RABEL_API_KEY as an environment variable, or put your key in place of YOUR_API_KEY in the snippets below.
Each one downloads the sample turn's words (/v1/sample.json), sends them to Bell at their times as a speech-to-text sends them, and prints Bell's guesses and the end of the turn.
TypeScript (Node 22), node snippet.ts:
const API = "https://api.rabellabs.com";
const KEY = process.env.RABEL_API_KEY ?? "YOUR_API_KEY";
const sample = await (await fetch(`${API}/v1/sample.json`)).json();
const ids = new Set();
const ws = new WebSocket(`${API.replace("https", "wss")}/v1/conversation`);
ws.onopen = () => {
ws.send(JSON.stringify({ key: KEY }));
console.log("Connecting to Bell...");
};
ws.onmessage = async (e) => {
const m = JSON.parse(e.data);
if (m.type === "guess") { ids.add(m.id); console.log("guess:", m.text); }
if (m.type === "end_of_turn") {
console.log("end of turn:", m.text, ids.has(m.guess_id) ? `(matched guess ${m.guess_id})` : "(no guess matched)");
ws.close();
}
if (m.type === "error") console.log("error:", m.message);
if (m.type === "ready") {
let t = 0;
for (const w of sample.words) { // the turn's words so far, each time your speech-to-text has new words
await new Promise((r) => setTimeout(r, w.ms - t));
t = w.ms;
ws.send(JSON.stringify({ type: "heard", text: w.text }));
}
await new Promise((r) => setTimeout(r, 200));
ws.send(JSON.stringify({ type: "end_of_turn", text: sample.final })); // its final words
}
};
Python, pip install websockets, then python snippet.py:
import asyncio, json, os, urllib.request
import websockets
API = "https://api.rabellabs.com"
KEY = os.environ.get("RABEL_API_KEY", "YOUR_API_KEY")
async def main():
sample = json.load(urllib.request.urlopen(urllib.request.Request(API + "/v1/sample.json", headers={"User-Agent": "rabel-api-snippet"})))
async with websockets.connect(API.replace("https", "wss") + "/v1/conversation") as ws:
await ws.send(json.dumps({"key": KEY}))
print("Connecting to Bell...", flush=True)
ids = set()
async def send():
t = 0
for w in sample["words"]: # the turn's words so far, each time your speech-to-text has new words
await asyncio.sleep((w["ms"] - t) / 1000)
t = w["ms"]
await ws.send(json.dumps({"type": "heard", "text": w["text"]}))
await asyncio.sleep(0.2)
await ws.send(json.dumps({"type": "end_of_turn", "text": sample["final"]})) # its final words
async for msg in ws:
m = json.loads(msg)
if m["type"] == "ready":
sender = asyncio.create_task(send())
elif m["type"] == "guess":
ids.add(m["id"])
print("guess:", m["text"])
elif m["type"] == "end_of_turn":
print("end of turn:", m["text"], f"(matched guess {m['guess_id']})" if m["guess_id"] in ids else "(no guess matched)")
break
elif m["type"] == "error":
print("error:", m["message"])
asyncio.run(main())
The same two files are in snippets/. More examples, with a speech-to-text of your own, starting a reply on Bell's guess, handling errors and a Pipecat agent, are in examples/EXAMPLES.md.
Keep the speech-to-text you use, and send Bell its words. Bell needs them while the speaker is talking: the partial words, as they come.
heard is your speech-to-text's interim (partial) transcript, and end_of_turn is its final transcript.
The end of the turn stays your speech-to-text's: send end_of_turn when it says the speaker has finished.
Bell has been run with Deepgram's speech-to-text: its streaming speech-to-text, and Deepgram Flux in the Pipecat example (see examples/EXAMPLES.md).
Open a WebSocket to /v1/conversation. Send the key first, either as the header Authorization: Bearer <key> or in the first text message (within 10 seconds).
The first message is the hello. Only key is required, and only when the header does not carry it:
{"type": "hello", "v": 2, "key": "<key>", "agent": "front-desk", "min_chance": 0.7, "learn": true}
agent: your agent's name, which Bell learns for: lower-case letters, digits, - and _, 1 to 64 characters, default when left out. What Bell learns for an agent belongs to your account, not to the key, so a new key keeps it. A new agent starts with nothing learned.demo-bank: a ready-made agent, already trained on a bank's callers, that every account can use. It never learns.min_chance: how sure Bell must be before it guesses, from 0.67 to 0.99; 0.7 when left out. A value out of range is brought into it, and ready says the value in force.learn: false and the conversation teaches the agent nothing. true when left out.host, host_version, hookup, vendor: what your agent runs on, if you want to say. Never required.A first message {"key": "<key>"} with no type is a hello with every field left out (the snippets above send that). With the key in the header and no hello within half a second, the conversation starts on the defaults; a hello sent later, before the first heard, is answered with a second ready.
The API answers with ready at once. Send words only after ready.
All are JSON text messages. The API takes text only.
{"type": "heard", "text": "<the turn's words so far>"}: send it each time your speech-to-text has new words. text is the whole turn so far, never only the new words.{"type": "end_of_turn", "text": "<the turn's final words>"}: send it when your speech-to-text ends the turn. The next heard opens the next turn.{"type": "ping", "id": <optional>}: answered with pong once every answer to the messages sent before it has gone out. Send it after a heard to know that Bell has nothing more to say to it. It is not part of a turn and teaches nothing.A conversation can hold several turns. To end it, close the socket once the last end_of_turn has come back. Fields the API does not know are ignored.
All are JSON text messages.
{"type": "ready", "v": 2, "agent", "min_chance", "hold_line", "learning", "calls_heard"}: Bell is ready; send the words. min_chance is the value in force; learning says whether this conversation teaches the agent; calls_heard is how many calls the agent has learned from. hold_line is for a hookup's check of an unsure last word.{"type": "guess", "turn", "id", "text", "heard", "chance"}: Bell's guess at the turn's words (text), the words heard when it was made (heard), and how sure Bell is (chance, at or over min_chance). At most one guess a turn, never equal to the words heard at the time it is made. An agent that has learned nothing sends none.{"type": "end_of_turn", "turn", "text", "guess_id", "right"}: the answer to your end_of_turn: its final words; right, whether the turn's guess equalled them, ignoring case and punctuation (null when there was no guess); guess_id, the guess's id when it was right, else null.{"type": "pong", "id"}: the answer to your ping, with its id when it carried one (a string, number, true, false or null).{"type": "error", "status", "error", "message", "retry_after_s"}: see below.guess and end_of_turn carry their turn's number as turn, from 0.
When a conversation closes, Bell learns from it for its agent: each turn's heard messages in order, and its final words. A turn is always guessed before it is learned from, and a conversation never learns from itself. A turn cut off by the close teaches nothing. Nothing is learned for demo-bank, or when the hello says "learn": false.
GET /v1/sample.json is a sample turn's words as a speech-to-text sends them: {"words": [{"ms", "text"}], "final"}. Each entry of words is the turn's words so far at ms milliseconds from the start; final is the turn's final words.
To see your account without your key, sign in by email: POST /v1/login with {"email": "you@example.com"} answers status 202, and
one email comes with a link that signs you in to your account page. The link works once and expires in 24 hours. It opens your account,
your use, codes and buying credit for an hour; it cannot open a conversation. GET /v1/login/confirm?token=... answers
{"email", "session", "expires_in_s"}; send the session as Authorization: Bearer <session> to the calls below.
Or sign in with Google: GET /v1/login/google, opened in your browser (the Continue with Google button on the log in page), signs
you in to the same account page when your Google account's email has an account. The sign-in has to come back from Google within
10 minutes, in the browser that started it; a sign-in cancelled at Google or not finished goes back to the log in page.
To replace a lost key, sign in and make a new one: POST /v1/keys with the header Authorization: Bearer <session> answers
{"key", "key_last4", "key_created"}. The key is shown only in this answer; your old key stops working at once. Signing up again with
the same email also gives a new key.
GET /v1/account with the header Authorization: Bearer <key> (or a session) answers {"email", "free_seconds_left",
"credit_cents", "price_usd_per_10000_minutes", "price_held_until", "used_seconds_month", "limits", "key_last4", "key_created"};
limits is {"seconds_a_conversation", "conversations_a_day", "conversations_at_once"}. price_usd_per_10000_minutes is the price
your account is charged now; price_held_until is the last day (UTC) your account keeps the price it signed up at, 12 months from
sign-up. A later change to the price does not reach your account before that day. key_last4 is the last four characters of your key (null for an older key, made
before they were kept); key_created is when it was made, in seconds since 1970 UTC.GET /v1/usage with the same header answers your use by day: {"unit": "seconds open", "days": [{"date", "seconds",
"conversations"}]}.POST /v1/codes/redeem with the same header and {"code": "..."} adds the code's free seconds to your account and answers
{"free_seconds_left"}. Each code works once for an account. A wrong, used-up or expired code answers 400 bad_code.POST /v1/billing/checkout with the same header and {"amount_cents": 500} answers {"url"}, Stripe's payment page for that
much credit. The credit is used after the free seconds, at your account's price.Use is metered in seconds open: the time a conversation is open, from ready until the socket closes, by the second. It is not the time of the speech in it.
All with the header Authorization: Bearer <key> (or a session).
GET /v1/agents answers {"agents": [...]}: your account's agents, each with its status as below, and demo-bank.GET /v1/agents/{agent} answers its status: {"agent", "calls_heard", "turns_heard", "guesses_sent", "guesses_right",
"head_start_ms_estimate", "guessing", "since", "last_call", "learning", "last_7_days"}. The numbers are totals since the agent
started; last_7_days holds the same numbers for the last 7 days (UTC, today included). guessing says whether Bell would send
guesses for this agent now, at min_chance 0.7. head_start_ms_estimate is the average time from sending a right guess to the
turn's end as the API saw it, in ms; the API cannot see whether your agent kept the reply it started, so it is an estimate. since
and last_call are UTC, to the minute. Calls with "learn": false and calls on demo-bank are not included.GET /v1/agents/{agent}/phrases answers what Bell holds for the agent in words: {"agent", "phrases", "more"}, the phrases in
alphabetical order, each once. Everything else Bell holds for the agent is in a coded form that cannot be read back as words. Take
?limit= (default 100, at most 1,000); when more is true, ask again with ?after= the last phrase you got. demo-bank's phrases
are Rabel's: for it this call answers 403 not_your_agent, though every account can use demo-bank and read its status.DELETE /v1/agents/{agent} forgets what Bell has learned for the agent and answers {"agent", "forgotten": true}. A conversation
open on it guesses nothing more and teaches nothing when it closes; the next conversation starts it again, with nothing learned.POST /v1/agents/{agent}/calls teaches the agent past calls:{"calls": [{"turns": [{"heard": ["i would like", "i would like to reset"], "final": "I would like to reset my password."}]}]}
Each turn carries its heard messages, your speech-to-text's interim words in the order it sent them, and its final words. It
answers {"agent", "calls_learned", "turns_learned", "calls_heard"}. At most 1,000 calls a request. A turn with no heard list, or a
call whose heard lists are all empty, answers 400 needs_heard: teaching from final words alone is not offered yet.
Every account can use demo-bank; a DELETE or a POST to it answers 409 read_only_agent. An agent your account does not
have answers 404 unknown_agent.
no_message).heard or end_of_turn text is at most 4,096 characters.key_at_once. When the API itself is full, a new conversation is refused with out_of_capacity. There is no daily limit.On the WebSocket an error is the message {"type": "error", "status", "error", "message", "retry_after_s"}. The socket closes after it, except after a bad_message for a text message, when the conversation stays open.
Over HTTP it is the status with {"error", "message"}.
| status | error |
when | retry_after_s |
|---|---|---|---|
| 401 | bad_key |
The key is wrong. | 0 |
| 402 | no_seconds |
The free seconds and the credit of this key are used up. | 0 |
| 429 | key_at_once |
This key already has 50 conversations open. | 1 |
| 529 | out_of_capacity |
Out of capacity, contact us for more usage. | 60 |
| 408 | no_message |
No message for 3,600 s. The conversation is closed. | 0 |
| 400 | bad_message |
A binary frame: the API takes text, the words of your speech-to-text, not audio. The socket closes. | 0 |
| 400 | bad_message |
A hello with a bad agent, min_chance or learn. The socket closes. |
0 |
| 400 | bad_message |
A text message other than heard or end_of_turn with a text, or ping, or a text over 4,096 characters. The conversation stays open. |
0 |
| 400 | needs_heard |
POST /v1/agents/{agent}/calls: a turn without its heard messages. |
|
| 403 | not_your_agent |
GET /v1/agents/demo-bank/phrases: demo-bank's phrases are Rabel's. |
|
| 404 | unknown_agent |
/v1/agents/{agent}: your account has no such agent. |
|
| 409 | read_only_agent |
DELETE or POST to demo-bank. |
POST /v1/signup answers 400 bad_email when the body has no email, and 429 too_many_signups after too many signups from one
address in an hour. GET /v1/confirm answers 400 bad_link for a link that is wrong, used or expired.