---
name: hollerback
description: Make phone calls and send texts through Hollerback. Use when the user wants someone phoned or texted to confirm, ask, schedule, or notify, and a structured answer back. Also use to follow a call live, listen in or take a call over, or share a call recording, redacted or not.
---

# Hollerback

> Hollerback makes phone calls and sends texts for AI agents. Your agent sends a goal and the facts it needs. A voice agent calls the person, or a text agent texts them, and returns one structured result. Your agent can also follow a call live, let a person listen in or take the call over, and share call recordings with sensitive details removed.

You need an API key. Your user creates one at https://hollerback.dev/dashboard/keys. Every request sends it as `Authorization: Bearer <key>`.

## Connect

Pick one. All three give the same tools. The task tools are `create_task`, `get_task`, `list_tasks`, `update_task`, `answer_question`, and `cancel_task`. The knowledge tools are `add_knowledge`, `get_knowledge`, and `remove_knowledge`. The live call tools are `watch_call`, `create_live_link`, `revoke_live_link`, and `call_operator`. The other tools manage numbers, calls, recordings, texts, the balance, opt-outs, and webhooks. The tool list has the full set.

### 1. MCP server

- URL: `https://hollerback.dev/api/mcp`
- Transport: Streamable HTTP
- Header: `Authorization: Bearer <key>`

Claude Code:

```bash
claude mcp add --transport http hollerback https://hollerback.dev/api/mcp --header "Authorization: Bearer $HOLLERBACK_API_KEY"
```

Any client that reads an `mcpServers` JSON file (Cursor, Windsurf, and others):

```json
{ "mcpServers": { "hollerback": { "url": "https://hollerback.dev/api/mcp", "headers": { "Authorization": "Bearer <key>" } } } }
```

A client that only runs local servers (Claude Desktop) can use the `mcp-remote` bridge:

```json
{ "mcpServers": { "hollerback": { "command": "npx", "args": ["-y", "mcp-remote", "https://hollerback.dev/api/mcp", "--header", "Authorization: Bearer <key>"] } } }
```

Setup for more clients: https://hollerback.dev/docs

### 2. Function tools over HTTP

Use this when your harness has function calling but no MCP client.

1. Load the tool definitions: `GET https://hollerback.dev/api/v1/tools?format=<format>`. The format is `anthropic`, `openai`, `openai-chat`, or `mcp`. This route needs no key.
2. Register them with your model.
3. When the model calls a tool, send its arguments as the JSON body of `POST https://hollerback.dev/api/v1/tools/<tool name>` with your key. Give the response body back to the model as the tool result.

```bash
curl -X POST https://hollerback.dev/api/v1/tools/list_numbers \
  -H "Authorization: Bearer $HOLLERBACK_API_KEY" -H "Content-Type: application/json" -d '{}'
```

A failed call returns an HTTP error status with `{ "error": { "code", "message" } }`. Give that body to the model too, so it can fix its arguments.

### 3. REST API

The OpenAPI description is at https://hollerback.dev/api/v1/openapi.json. A TypeScript client lives in `packages/client` of the Hollerback repository.

Recordings, share links, live links, and operator calls have REST routes too:

- `GET https://hollerback.dev/api/v1/calls/<call ID>/recording` returns the MP3. Add `?redact=true` for the redacted recording. While redaction runs, the route answers `202` with a `Retry-After` header. Ask again after that many seconds.
- `POST` and `GET https://hollerback.dev/api/v1/calls/<call ID>/recording/shares` create and list share links. `DELETE .../shares/<share ID>` revokes one.
- `POST https://hollerback.dev/api/v1/tasks/<task ID>/live-links` creates a live link. `DELETE .../live-links/<link ID>` revokes one.
- `POST https://hollerback.dev/api/v1/tasks/<task ID>/operator-calls` calls an operator into the live call.

To follow a call while it runs, read Server-Sent Events from `GET https://hollerback.dev/api/v1/tasks/<task ID>/events` or `GET https://hollerback.dev/api/v1/calls/<call ID>/events` with your key. The task stream follows each call of the task in turn.

- A `turn` event carries one turn: `callId`, `index`, `speaker`, `text`, and `at`.
- A `state` event carries one state change: `callId`, `type`, `at`, and `operator` for takeovers. Companion events add `screenId`, `optionIds`, and `title` (a screen's title).
- The stream sends `ended` and closes when the call ends. It also closes after about 290 seconds.
- Each event's `id` is a cursor. Reconnect with the `Last-Event-ID` header, or the `cursor` query parameter, to get only what you missed. A standard EventSource client reconnects on its own. Once the call has ended and you have every event, the stream answers `204`, and EventSource stops. The task stream answers `204` only after the task has ended too.

## Webhooks

Instead of polling, set a webhook URL at https://hollerback.dev/dashboard/settings. Events: `task.updated`, `task.completed`, `task.open_question`, `task.followup_created` (the person called back after the task ended, so a new task started), and `inbound.unknown`.

Two events are about calls and recordings:

- `call.turn`: one turn of a live call. Only tasks created with `live: { "turnWebhooks": true }` send it. The payload has `taskId`, `callId`, `metadata`, `index`, and `turn` (`speaker`, `text`, `at`). A companion selection sends the same event with `type: "companion_selected"`, `screenId`, `optionIds`, and `at` in place of `index` and `turn`.
- `recording.redacted`: a redacted recording is ready or has failed. The payload has `callId`, `taskIds`, and `state` (`ready` or `failed`). A ready recording adds `coverage` (`entities`, or `numbers_only` for a call not in English) and `spanCount`. A failed one adds `error`.

Each request has `Hollerback-Signature: t=<unix seconds>,v1=<hex>`. `v1` is the HMAC-SHA256 of `<t>.<raw body>` with your signing secret. Reject requests older than 5 minutes.

# Using Hollerback

Hollerback reaches people by phone and by text for you. You describe one goal and the facts it needs. A voice agent calls the person, or a text agent texts them, handles voicemail, callbacks, and replies, and returns one structured result.

## Workflow

1. Call `list_numbers` to get a `numberId`. If the list is empty, ask your user before you call `buy_number`. A number costs a monthly fee.
2. Call `create_task` with the person, the goal, the facts, and a `resultSchema`.
3. Wait for the result. Pass `wait_seconds` (up to 240) to `create_task` to wait inside the call. A task often takes longer than that: the person may not answer, or the call may fall outside calling hours. When `create_task` returns an open state, call `get_task` later.
4. Read `result.state` and act on it. The table below says what each state means.
5. If the state is `waiting_for_answer`, read `openQuestions`. Get the answer from your user or your own data, then call `answer_question`. The voice agent calls the person back with the answer.

## Writing a good task

- `goal`: one outcome in one or two sentences. Say what counts as done. Example: "Ask Dana to cover the Tuesday shift. Get a yes or no."
- `context`: the facts the voice agent brings up on every call, one fact per string. Keep it to what the goal needs.
- `knowledge`: everything else the person might ask about. The next section explains it. The voice agent says nothing that is not in `context` or `knowledge`.
- `authority`: what the voice agent may offer or agree to. An empty list means it may agree to nothing. Example: "You may offer a $20 bonus for covering the shift."
- `resultSchema`: a JSON Schema object with `type: "object"` and up to 30 properties. Give each property a `description`. The voice agent fills these fields from the conversation.
- `person`: `name` and `phone` are required. Add `timeZone` (IANA, such as `America/Chicago`) so the call happens at a reasonable local hour. Add `pronunciation` when the name is easy to say wrong.
- `onBehalfOf`: the person or team the call is for, such as "the store manager". The voice agent opens with "calling for <onBehalfOf> at <company>". The company comes from the number.
- `consent`: `{ "confirmed": true, "source": "<how you got consent>" }`. Only call people who agreed to be called.
- `purpose`: `support`, `employee`, or `account_notice`. Sales and marketing calls are not allowed.
- `metadata`: string pairs that come back unchanged on the task and its webhooks. Use it for your own IDs.
- `callAnytime`: set `true` to call outside calling hours, such as an urgent shift at 5 a.m. Retries then also happen at any hour. Use it only when the person expects calls at any hour.
- `channel`: `call` (the default), `text`, or `text_then_call`. The next section explains texts.

## Text tasks

A text task works toward the same goal and returns the same result as a call. A text agent writes the texts, reads the replies, and ends the conversation.

- `channel: "text"` works only by text. Each attempt is one text thread. A thread waits 4 hours for a reply before the next attempt.
- `channel: "text_then_call"` sends one text thread first. If the person does not reply, the remaining attempts are calls.
- Set `consent.texts` to `true`. Only text people who agreed to texts about this.
- Texts may carry the goal, `context`, and `knowledge`. Texts show on lock screens and shared phones, and a text cannot confirm who reads it. Use a call task for private details.
- The number must show `textTasks: true` in `get_texting_status`. Otherwise `create_task` fails with `texting_not_enabled`.
- Hollerback adds a greeting that names the company and says it is an AI assistant, and an opt-out line, to the first text. A text task's texts never contain links or phone numbers. The companion link text is the one text with a link.
- A person may call the number instead of replying. The call then handles the task. A person who asks for a call by text gets one.
- Each attempt in `attempts` has a `channel`. A text thread's `transcript` lists the texts in order.

## Companion page

A companion page shows a person the options from your task on their phone, during a call. The voice agent texts the person a link. The person taps an option on the page. The tap goes back to the voice agent at once, and to you as a selection on the task.

Set up first:

- Register the organization for texting. The companion link goes out under the same registration as other texts. There is no separate step and no extra fee.
- Read the number's `companion` state in `list_numbers` or `get_texting_status`: `off`, `pending`, or `on`. Only `on` can send a link. A number is `pending` while carriers review the registration, and `on` once texting is approved for it.
- A sales number cannot send a companion link. A number stays `off` when its registration was approved before texts could carry links.

Fields on a task:

- `companion.options`: 1 to 50 options. Each has `id` (1 to 64 characters, unique in the task), `title` (up to 80), and optional `description` (up to 300), `detail` (up to 80, a short line such as a price), and `imageUrl`.
- `imageUrl` must be HTTPS and must return a JPEG, PNG, or WebP image of 5 MB or less. Hollerback copies each image when you create the task. A failed copy fails `create_task` with `companion_image_unreachable`, and the message names the option.
- A companion needs a `call` or `text_then_call` channel, `consent.texts: true`, and a number whose `companion` state is `on`. A sales task cannot have one. Otherwise `create_task` fails with `companion_not_enabled`.

How a call works:

- The voice agent knows the options and can say them without a screen.
- The voice agent asks the person before it texts the link. If the person says no, the call goes on by voice.
- The first screen sends the link. The text costs the standard text price and shows in `list_messages` with `kind: "companion_link"`. The voice agent can send the link again once if the text did not arrive.
- Each call has its own link. A retry, a callback, or an inbound call gets a new one. On an inbound call that serves several tasks, only the first task with options gets screens.
- A screen is a `choice` (the person taps options and confirms) or `details` (read-only). The voice agent writes only the screen title. Each card shows your option text and image.
- Hollerback rejects a screen title with a number that no shown option or `context` line contains. This stops a made-up price or date.
- A selection is final when the person taps the confirm button. A later selection on the same screen replaces the earlier one. The voice agent hears each one.
- The page shows only the company name and the current screen. It never shows the person's phone number, the transcript, or other task fields.
- The page stays readable for 30 minutes after the call ends, then the link expires.
- A reply of STOP to the link text opts the person out and ends their open tasks, as it does for any text.

What you get back:

- `get_task` returns `companion`: your `options`, and `calls`, one record per call. A record has `linkSentAt`, `openedAt`, `resends`, every screen shown, and every selection by option ID. The page writes it, not the model. `companion` is null for a task with no options.
- The voice agent may copy a selection into a `resultSchema` field. Trust `companion.calls[].selections` over that copy.
- `watch_call` and the event streams add the events `companion_sent`, `companion_opened`, `companion_screen`, and `companion_selected`. They carry `screenId` and `optionIds`, never the link.
- The `task.completed` webhook carries `companion`. With `live: { "turnWebhooks": true }`, each selection also sends a `call.turn` webhook with `type: "companion_selected"`, `screenId`, and `optionIds` in place of `index` and `turn`.
- The page itself answers its taps with `screen_replaced` (the voice agent showed a newer screen), `call_ended`, `companion_link_expired`, and `too_many_selections`. These reach the person's browser, not your code.

## Knowledge

People ask questions the goal does not cover, such as "Which store is it shipping from?" When the voice agent cannot answer, the task waits in `waiting_for_answer` and the voice agent must call back. Send knowledge to prevent that. The voice agent searches it during the call and states it only when the person asks.

- Send it in the `knowledge` field of `create_task`, or add it to an open task with `add_knowledge`. Read it with `get_knowledge`. Remove entities and documents by ID, or links by `from`, `relation`, and `to`, with `remove_knowledge`.
- `entities`: named things, each with an `id` you choose, a `type`, a `name`, optional `aliases`, and `facts` in plain sentences. Example: `{ "id": "order_1182", "type": "order", "name": "Order 1182", "facts": ["Shipped on October 28."] }`.
- `links`: `{ "from", "relation", "to" }` between entity IDs, such as order_1182 → shipped from → elm_store. A search for the order then also returns the store's facts.
- `documents`: `{ "id", "title", "text" }` for a policy or an FAQ you have as plain text.
- Send what you have about the person and the topic: their account, orders, appointments, the places and people involved, prices, and policies.
- Limits per task: 500 entities, 2,000 links, 50 documents, 1 MB in total. An item with the same ID replaces the old one.
- A call in progress keeps the knowledge it started with. Each attempt lists its `lookups`: what the voice agent searched for and what it found.

## Rules

- US and Canadian phone numbers only.
- Calling hours also apply to texts Hollerback starts. A text that answers the person's reply goes out at any hour.
- US calls happen from 8 a.m. to 9 p.m. in the person's time zone. Without a time zone, US calls happen from 11 a.m. to 9 p.m. Eastern. Outside those hours the task waits in `queued`.
- Canadian calls happen from 9:30 a.m. to 8 p.m. on weekdays, 10:30 a.m. to 5 p.m. on Saturday, and noon to 5 p.m. on Sunday, in the person's time zone. A task for a Canadian number must set `person.timeZone`.
- A task with `callAnytime: true` skips these hours.
- The task makes up to `maxAttempts` attempts (default 3) before it ends as `unreachable`. An attempt is one call or one text thread.
- Each task expires after `expiresInHours` (default 168).
- If a person asked not to be called again, `create_task` fails with `opted_out`. Do not retry.

## Task states

| State | Open or ended | What to do |
|---|---|---|
| `queued` | open | Nothing. The call starts at the next allowed time. |
| `in_progress` | open | Nothing. A call is happening now, or the text agent is writing a text. |
| `waiting_for_reply` | open | Nothing. The person missed the call, asked for a callback, or has not replied to a text yet. The next step is at `nextAttemptAt`. |
| `waiting_for_answer` | open | Answer the blocking question in `openQuestions` with `answer_question`. |
| `goal_met` | ended | Read `result.fields`. |
| `declined` | ended | The person said no. `result.declineReason` says why. Do not call again about the same goal. |
| `unreachable` | ended | Nobody answered on any attempt. Tell your user. |
| `needs_human` | ended | The person asked for a human or raised something outside the goal. `result.humanRequest` says what. Tell your user. |
| `expired` | ended | The task ran past its expiry. |
| `cancelled` | ended | Someone cancelled it. |

Every ended task has `result.summary`, `result.corrections` (facts the person said were wrong), and `result.openQuestions`. Pass corrections to your user. Fix your own records with them.

## Finding and changing tasks

- `list_tasks` returns tasks newest first. Filter with `state`. When `nextCursor` is not null, pass it as `cursor` to get the next page.
- `update_task` with `addContext` adds facts to an open task. With `authority`, it replaces the whole authority list.
- `cancel_task` stops all future calls.

## Live calls

You can follow a call while it runs, and a person from your organization can listen to it or take it over.

- `watch_call` follows the task's current call while it runs. It returns new `turns` and `events` (state changes) as soon as they happen, or after `wait_seconds` (default 30, at most 60). Pass the returned `cursor` to the next `watch_call`.
- `state` is `waiting` (no call has started), `ringing`, `live` (the person answered), or `ended`. `operator` names the person who has the call, or is null while the voice agent has it.
- `ended` means this call ended. Stop watching and call `get_task`. If the task is still open, it calls again at `nextAttemptAt`, and `watch_call` then follows the new call from its first turn.
- `watch_call` follows calls only. On a text task it stays `waiting`. Read the texts with `list_messages` and `taskId`.
- `create_task` with `live: { "turnWebhooks": true }` sends a `call.turn` webhook for each turn while the call runs. It is off by default, because it sends many webhooks.
- The call's state changes are `ringing`, `answered`, `takeover_started`, `handed_back`, `operator_call_failed`, and `ended`. A takeover event names the operator.
- `create_live_link` gives a link a person can open to listen to the task's call while it runs. Mode `takeover` also lets them take the call over. Post the `url` in your chat for the person who asked. The `url` appears only in this response. The link waits for the call if it has not started, and expires when the task ends or after 24 hours. `revoke_live_link` stops one, and anyone listening with it leaves the call.
- `call_operator` calls a person from your organization into the task's live call. Pass their `phone` and their `name`. The voice agent says the name to the person before the handoff. It works only while `watch_call` shows `live`. When the operator answers, the voice agent hands the call to them. They press * to hand it back and # to end the call. Their phone leg costs the same per minute as a call. If they do not answer, the call gets an `operator_call_failed` state change.
- Before a takeover, the voice agent tells the person who is joining. After a hand back, it says "This is the assistant again" and continues toward the goal.
- Only one operator can have the call at a time. Any number of people can listen.
- An operator who leaves without handing back gets 10 seconds to return. Then the voice agent takes the call back.
- An operator's turns appear in the transcript with `speaker: "operator"`. An operator may agree to things outside `authority`. The result reports what was agreed.
- Every call opens with "This call is recorded and may be monitored." Your organization's `liveLinks` setting decides what live links may do.

## Recordings

`share_recording` creates a link that plays one call's recording and transcript. The call ID is an attempt's `id` in `get_task`, or an `id` from `list_calls`. Text threads have no recording. The `url` appears only once, so pass it on right away. `list_recording_shares` lists a call's links with their views and expiry. `revoke_recording_share` stops one at once.

- A share link is redacted by default. A tone replaces sensitive details in the audio, and the transcript leaves them out. Set `redact: false` for the recording as it was recorded.
- Redaction removes personal, payment, and health details in English calls. A call in another language gets number redaction only.
- Redaction costs 2.5 cents per call minute, charged once per call. The total rounds up to a whole cent. An unredacted share is free.
- A link lasts `expiresInSeconds`: 7 days by default, 30 days at most. Add a `label` that says who the link is for.
- The link works at once. Its page says "Preparing the recording" until redaction is ready. The `recording.redacted` webhook fires when the redacted recording is ready or has failed.

Redacted or not:

- Use a redacted share for any link that leaves your organization: a CRM, a vendor, a contractor, or a person who was not part of the task. Also use one for any link posted in a chat or a ticket, because those get copied.
- An unredacted share fits internal review where the detail matters, a dispute over what was said, or a legal request. Give it a short expiry and a label that says why, and revoke it when the review is done.
- Redaction is best effort. Speech recognition misses words, and a missed word is a missed redaction. Redaction does not make a recording safe to publish. It does not make your organization HIPAA or PCI compliant.
- The voice agent never asks for a card number, a bank account number, or a Social Security number. If a person reads one anyway, the original recording holds it.
- The person agreed to a recorded call. They did not agree to wide distribution. Your organization is responsible for whom it shares recordings with.

## Managing the account

Ask your user before you call a tool that costs money or cannot be undone: `buy_number`, `release_number`, `call_operator`, and `remove_opt_out`.

- Numbers: `update_number` changes the company name, label, or instructions for unknown callers. `release_number` gives a number back. It fails while the number has open tasks or a call in progress.
- Calls: `list_calls` and `get_call` return every call with its transcript, including calls from unknown callers, which have no task. Text threads are not calls: read them on their task.
- Texts: `get_texting_status` says whether texting is on for each number. `list_messages` and `get_message` return texts sent and received. Pass `taskId` to `list_messages` to see one task's texts. Texts for call tasks never carry task details. Texts for text tasks do.
- Balance: `get_account` returns the balance and today's spending. `list_ledger` lists every charge and top-up. A redaction is a `redaction` line, and an operator's phone leg is an `operator_call` line.
- Settings: `update_account` changes the display name, the webhook URL, and `redactEveryCall` (default `false`). `true` redacts every recorded call when it ends, and charges for each. `get_account` also returns two settings that only the dashboard changes. `update_account` fails with `invalid_request` if you send either one:
  - `unredactedSharesAllowed` (default `true`): `false` allows only redacted share links.
  - `liveLinks` (default `listen_and_takeover`): `off` turns live links off, `listen` allows listening only, and `listen_and_takeover` also allows takeovers and `call_operator`.
- Opt-outs: `list_opt_outs`, `add_opt_out`, and `remove_opt_out`. Remove one only when the person asked to be contacted again.
- Webhooks: `list_webhook_deliveries` shows each event's status and last error. `retry_webhook_delivery` sends one again. `send_test_webhook` sends a test event.

## Errors

A failed tool call returns `{ "error": { "code", "message" } }`.

| Code | Meaning |
|---|---|
| `invalid_request` | An argument is missing or wrong. The message names the field. Fix it and retry. |
| `invalid_phone` | The phone number is not a valid US or Canadian number. |
| `time_zone_required` | A Canadian number needs `person.timeZone` unless `callAnytime` is true. Set it and retry. |
| `unauthorized` | The API key is missing or revoked. |
| `insufficient_balance` | The account has no funds. Ask your user to add funds. |
| `daily_limit` | The account reached its daily spend limit. Try again tomorrow or ask your user. |
| `opted_out` | The person asked not to be called. Do not retry. |
| `text_consent_required` | A text channel needs `consent.texts: true`. |
| `texting_not_enabled` | The number cannot send text tasks yet. Check `get_texting_status`, or use `channel: "call"`. |
| `companion_not_enabled` | The task or the number cannot use a companion. The message says which rule failed. |
| `companion_image_unreachable` | Hollerback could not fetch an option's image, or the image is not JPEG, PNG, or WebP of 5 MB or less. The message names the option. |
| `number_not_found`, `task_not_found`, `question_not_found`, `call_not_found`, `message_not_found` | The ID is wrong or belongs to another account. |
| `number_in_use`, `number_in_call` | The number has open tasks or a call in progress, so it cannot be released yet. |
| `task_ended` | The task has ended, so it cannot change. |
| `already_answered` | Someone already answered that question. |
| `task_changed` | The task changed while you wrote to it. Read it and try again. |
| `knowledge_limit` | The task's knowledge would pass a limit. Nothing was saved. Send less. |
| `unknown_entity` | A link names an entity ID the task does not have. Add the entity in the same request. |
| `recording_not_found` | The call has no recording yet, or its recording was deleted. |
| `unredacted_shares_disabled` | Your organization allows only redacted share links. Leave out `redact` or set it to `true`. |
| `expiry_too_long` | `expiresInSeconds` is over 30 days (2592000 seconds). Use a shorter expiry. |
| `share_not_found` | The share ID is wrong or belongs to another call. |
| `redaction_failed` | The redacted recording could not be made. Tell your user. |
| `live_links_disabled` | Your organization turned live links off. |
| `takeover_disabled` | Your organization allows only listening. Use mode `listen`, and do not call `call_operator`. |
| `live_link_not_found` | The live link ID is wrong or belongs to another task. |
| `no_live_call` | No call is live on the task right now. Try again once `watch_call` shows `live`. |
| `call_taken_over` | An operator already has the call. Wait for `handed_back`. |
| `live_unavailable` | Live calls are not set up on this server. |
| `tool_not_found` | Over HTTP only: the tool name in the URL is wrong. |
