Dubber API Patterns
Overview
Dubber records calls from telecom systems (for example BroadWorks) and keeps them as
compliance records. The dubber-mcp sidecar mints and caches Dubber OAuth tokens
itself; Conduit stores the customer's credentials and forwards them as headers on every
call. Start any troubleshooting with dubber_test_connection.
Dubber is a preview vendor in Conduit: wired and catalog-visible, but not yet confirmed
by a live customer call. Report unexpected response shapes as findings, not as user error.
Credentials
The fields are entered once in the Conduit web UI (/connect/dubber). Nothing is set on
the client, and Conduit drops any X-Dubber-* header a client sends.
| Conduit field |
Header |
Notes |
| Client ID |
X-Dubber-Client-Id |
Mashery application key (developer.dubber.net) |
| Client Secret |
X-Dubber-Client-Secret |
Mashery application secret |
| Auth ID |
X-Dubber-Auth-Id |
Dubber portal, API tab. Not a person's login. |
| Auth Token |
X-Dubber-Auth-Token |
Dubber portal, API tab |
| Region (optional) |
X-Dubber-Region |
sandbox (default), us, au, eu, uk |
The token request is an OAuth password grant where username/password are the Auth
ID/Auth Token pair. All four required values must be present; the sidecar answers 401
before any tool runs if one is missing.
Region picks the host path api.dubber.net/<region>/v1. A blank region means
sandbox, so a production customer connected without a region is talking to the
sandbox, not their tenant. If every call returns empty or 403, check the region first.
Key concepts
- Hierarchy. Group, then account, then users and Dub.Points, then recordings. There is
no "list all accounts" or "list all groups" tool. Ask the user for the account ID (or a
group ID and use
dubber_groups_get). dubber_profile_get shows the authenticated
identity, which can help confirm whose credentials are connected.
- Dub.Point. One recorded line or endpoint, connected to an external telecom system.
Recordings belong to a Dub.Point. A Dub.Point's
user field is a URL ending in
/users/<USER_ID>, not a bare ID. dubber_dub_points_find looks one up by
external-system identifiers.
- Unidentified recordings. Calls Dubber captured but could not match to an account or
Dub.Point. They sit on the group:
dubber_groups_list_unidentified_recordings.
- A token proves the credentials, not access.
dubber_test_connection succeeding does
not prove the token can read any particular account.
Pagination
dubber_recordings_list is the only paged tool:
- Newest first.
limit 1 to 500 (default 100), offset skips matching recordings.
startTimeFrom (inclusive) and startTimeTo (exclusive for date-times; a date-only
value includes the whole day) filter on start_time. Values without an offset are UTC;
pass an explicit offset for a customer's local day.
dubPointId or teamId, never both. There is no user filter on recordings.
- Dubber has no server-side date filter, so the sidecar filters after fetching. One call
scans at most 2,500 recordings (25 Dubber requests). When
hasMore is true, call again
with cursor=<nextCursor>, offset=<remainingOffset> and the same filters.
scanCapReached=true means the cap stopped the scan, not the end of the data.
dubber_dub_points_list, dubber_users_list, dubber_notifications_list,
dubber_groups_list_unidentified_recordings and dubber_notifications_list_unclaimed take
no paging arguments and return one Dubber page. Dubber's default page for Dub.Points is 20
items, so a Dub.Point list of exactly 20 may be truncated. Say so in any report built from
it.
Errors and rate limits
| Symptom |
Likely cause |
Action |
dubber_test_connection fails |
Wrong Client ID/Secret or Auth ID/Token, or wrong region |
Re-check the values and the region in Conduit |
| 403 "Account Inactive" |
Mashery app or Dubber account not active for that region |
Confirm the region and app status with Dubber |
| Token works, a tool returns 403 or 404 |
Credentials cannot see that account, user or recording |
Confirm the ID belongs to the connected tenant |
| 429 |
Rate limit reached |
Wait; reads are retried automatically |
| Tool refuses with a confirmation message |
Gated tool called without consent |
See "Confirmation" below |
Dubber's getting-started guide documents a limit of 500 calls per token in 24 hours. A
token lasts about 24 hours. Each dubber_recordings_list call can make up to 25 Dubber
requests, so a wide multi-account sweep can use a large share of the day's budget. Narrow
by dubPointId and a date window before scanning everything.
The sidecar retries reads (GET) on 429 and 5xx. It never retries a write. After a failed
write, check the current state with a read before trying again.
Confirmation
dubber_recordings_delete, dubber_recordings_delete_tags, dubber_users_delete,
dubber_notifications_delete and dubber_oauth_revoke_token ask before acting. Conduit
cannot show that prompt, so they refuse unless the call includes
confirm_destructive_action: true. Only pass it after the user has agreed to that specific
action in the conversation.
Conduit permission tiers
| Tier |
Tools |
| Admin |
dubber_users_delete, dubber_oauth_revoke_token |
| Write |
every create, update, activate, tag, upload and delete tool other than the two above, including dubber_recordings_delete |
| Read |
every get, list and find tool, plus dubber_test_connection and dubber_profile_get |
A caller below the required tier is refused by Conduit before the call reaches Dubber.
dubber_recordings_delete is only write tier even though it is irreversible.
Gotchas
dubber_oauth_revoke_token revokes the token every in-flight call is using. The next
call mints a new one, but parallel work fails in the meantime. It is not a credential
rotation; the Auth ID/Token stay valid.
- The plugin cannot fetch audio. Send the user to the Dubber portal to listen.
data, metadata and query object arguments are passed to Dubber as-is. Dubber does
not publish a full schema, so read the current object with a get tool first and change
only the fields you need.
1---2name: dubber-api-patterns3description: >4 How the Dubber tool surface behaves through Conduit: the five X-Dubber-*5 credential headers and the password-grant token they mint, region6 selection, the account/group/Dub.Point/recording hierarchy, how7 dubber_recordings_list pages and filters, which list tools return a single8 page, the error and rate-limit behaviour, the confirm_destructive_action9 flow, and which tools Conduit treats as read, write or admin.10when_to_use: >-11 When calling any Dubber tool, diagnosing a Dubber connection or permission12 failure, or deciding whether a Dubber operation is possible. Use when:13 dubber credentials, dubber 401, dubber 403, account inactive, dubber region,14 dubber test connection, dubber paging, dubber rate limit, dubber admin tier.15metadata:16 source: https://skillmd.com/skills/wyre-ai/dubber-api-patterns17---1819# Dubber API Patterns2021## Overview2223Dubber records calls from telecom systems (for example BroadWorks) and keeps them as24compliance records. The dubber-mcp sidecar mints and caches Dubber OAuth tokens25itself; Conduit stores the customer's credentials and forwards them as headers on every26call. Start any troubleshooting with `dubber_test_connection`.2728Dubber is a **preview** vendor in Conduit: wired and catalog-visible, but not yet confirmed29by a live customer call. Report unexpected response shapes as findings, not as user error.3031## Credentials3233The fields are entered once in the Conduit web UI (`/connect/dubber`). Nothing is set on34the client, and Conduit drops any `X-Dubber-*` header a client sends.3536| Conduit field | Header | Notes |37|---|---|---|38| Client ID | `X-Dubber-Client-Id` | Mashery application key (developer.dubber.net) |39| Client Secret | `X-Dubber-Client-Secret` | Mashery application secret |40| Auth ID | `X-Dubber-Auth-Id` | Dubber portal, API tab. Not a person's login. |41| Auth Token | `X-Dubber-Auth-Token` | Dubber portal, API tab |42| Region (optional) | `X-Dubber-Region` | `sandbox` (default), `us`, `au`, `eu`, `uk` |4344The token request is an OAuth password grant where `username`/`password` are the Auth45ID/Auth Token pair. All four required values must be present; the sidecar answers 40146before any tool runs if one is missing.4748Region picks the host path `api.dubber.net/<region>/v1`. A blank region means49**sandbox**, so a production customer connected without a region is talking to the50sandbox, not their tenant. If every call returns empty or 403, check the region first.5152## Key concepts5354- **Hierarchy.** Group, then account, then users and Dub.Points, then recordings. There is55 no "list all accounts" or "list all groups" tool. Ask the user for the account ID (or a56 group ID and use `dubber_groups_get`). `dubber_profile_get` shows the authenticated57 identity, which can help confirm whose credentials are connected.58- **Dub.Point.** One recorded line or endpoint, connected to an external telecom system.59 Recordings belong to a Dub.Point. A Dub.Point's `user` field is a URL ending in60 `/users/<USER_ID>`, not a bare ID. `dubber_dub_points_find` looks one up by61 external-system identifiers.62- **Unidentified recordings.** Calls Dubber captured but could not match to an account or63 Dub.Point. They sit on the group: `dubber_groups_list_unidentified_recordings`.64- **A token proves the credentials, not access.** `dubber_test_connection` succeeding does65 not prove the token can read any particular account.6667## Pagination6869`dubber_recordings_list` is the only paged tool:7071- Newest first. `limit` 1 to 500 (default 100), `offset` skips matching recordings.72- `startTimeFrom` (inclusive) and `startTimeTo` (exclusive for date-times; a date-only73 value includes the whole day) filter on `start_time`. Values without an offset are UTC;74 pass an explicit offset for a customer's local day.75- `dubPointId` or `teamId`, never both. There is no user filter on recordings.76- Dubber has no server-side date filter, so the sidecar filters after fetching. One call77 scans at most 2,500 recordings (25 Dubber requests). When `hasMore` is true, call again78 with `cursor=<nextCursor>`, `offset=<remainingOffset>` and the same filters.79 `scanCapReached=true` means the cap stopped the scan, not the end of the data.8081`dubber_dub_points_list`, `dubber_users_list`, `dubber_notifications_list`,82`dubber_groups_list_unidentified_recordings` and `dubber_notifications_list_unclaimed` take83no paging arguments and return one Dubber page. Dubber's default page for Dub.Points is 2084items, so a Dub.Point list of exactly 20 may be truncated. Say so in any report built from85it.8687## Errors and rate limits8889| Symptom | Likely cause | Action |90|---|---|---|91| `dubber_test_connection` fails | Wrong Client ID/Secret or Auth ID/Token, or wrong region | Re-check the values and the region in Conduit |92| 403 "Account Inactive" | Mashery app or Dubber account not active for that region | Confirm the region and app status with Dubber |93| Token works, a tool returns 403 or 404 | Credentials cannot see that account, user or recording | Confirm the ID belongs to the connected tenant |94| 429 | Rate limit reached | Wait; reads are retried automatically |95| Tool refuses with a confirmation message | Gated tool called without consent | See "Confirmation" below |9697Dubber's getting-started guide documents a limit of 500 calls per token in 24 hours. A98token lasts about 24 hours. Each `dubber_recordings_list` call can make up to 25 Dubber99requests, so a wide multi-account sweep can use a large share of the day's budget. Narrow100by `dubPointId` and a date window before scanning everything.101102The sidecar retries reads (GET) on 429 and 5xx. It never retries a write. After a failed103write, check the current state with a read before trying again.104105## Confirmation106107`dubber_recordings_delete`, `dubber_recordings_delete_tags`, `dubber_users_delete`,108`dubber_notifications_delete` and `dubber_oauth_revoke_token` ask before acting. Conduit109cannot show that prompt, so they refuse unless the call includes110`confirm_destructive_action: true`. Only pass it after the user has agreed to that specific111action in the conversation.112113## Conduit permission tiers114115| Tier | Tools |116|---|---|117| Admin | `dubber_users_delete`, `dubber_oauth_revoke_token` |118| Write | every create, update, activate, tag, upload and delete tool other than the two above, including `dubber_recordings_delete` |119| Read | every get, list and find tool, plus `dubber_test_connection` and `dubber_profile_get` |120121A caller below the required tier is refused by Conduit before the call reaches Dubber.122`dubber_recordings_delete` is only write tier even though it is irreversible.123124## Gotchas125126- `dubber_oauth_revoke_token` revokes the token every in-flight call is using. The next127 call mints a new one, but parallel work fails in the meantime. It is not a credential128 rotation; the Auth ID/Token stay valid.129- The plugin cannot fetch audio. Send the user to the Dubber portal to listen.130- `data`, `metadata` and `query` object arguments are passed to Dubber as-is. Dubber does131 not publish a full schema, so read the current object with a get tool first and change132 only the fields you need.