# Get voice catalog

List available team-inbox voice capabilities, their revisions, configured bindings and eligible booking links.

POST https://api.brigg.app/v1/operations/voice.GetVoiceCatalog

## Access & visibility

Allow `voice.GetVoiceCatalog` on your API key. Resource read permissions: `core:Inbox`.

**Workspace access by default.** Private member data requires [approved member delegation](https://developer.brigg.app/authentication#member-delegation) through `Brigg-Act-As`; the key supplies permissions while private ownership and project boundaries remain enforced.

[Set up authentication](https://developer.brigg.app/authentication) · [Choose permissions](https://developer.brigg.app/permissions)

## Request

No parameters. Send an empty JSON object (`{}`).

## Bind a capability to an inbox

[Get voice catalogue](https://developer.brigg.app/reference/voice/GetVoiceCatalog) returns team/inbox `offerings` and existing `bindings`. An offering supplies a capability such as booking; it is not a speech voice. Copy its `key` to the request's `offering_key`, and copy `revision` exactly. Only enable an available offering. For built-in meeting booking, supply `settings.booking_link_id` from the catalogue's `meetings`: the link must be active and must not require extra questions unsupported by phone booking.

Select the request's `inbox_id` from [List inboxes](https://developer.brigg.app/reference/support/ListInboxes). The inbox must have an assigned agent and the acting member must have inbox-management authority. A personal assistant instead requires its owner's identity; workspace delegation does not bypass that ownership check. The public catalogue describes the team/inbox workflow.

Add creates a binding. Update requires the binding's existing `id` and its original inbox; it cannot move a binding between inboxes. Binding responses call these fields `inbox_id` and `offering_key`; requests use `inbox_id` and `offering_key`. Submit the complete desired `offering_key`, `revision`, `enabled` and `settings`: update is not a partial settings patch. Read the catalogue first to preserve settings you want to retain.

A 409 means an offering is no longer available or its revision changed. Re-read the catalogue, review the new capability and submit a new logical request with the reviewed revision. A 400 can mean invalid booking settings; 403 means the acting member cannot manage the target. Inspect the error message for the cause. Test the inbox with [Start voice test](https://developer.brigg.app/reference/voice/StartVoiceTest) after changing its capabilities.

## Response

Returns **200 OK** with a JSON body.
| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `offerings` | array of [VoiceOffering](#voiceoffering-response-offerings) | Yes | Available voice capabilities that can be bound to an inbox assistant. |
| `bindings` | array of [object](#response-bindings) | Yes | Configured connections between an inbox assistant and voice capabilities. |
| `meetings` | array of [object](#response-meetings) | Yes | Booking links available to the voice assistant. |

### VoiceOffering · response.offerings[]

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `key` | string | Yes | Stable key identifying this option within its collection; distinct from its display label. |
| `source` | [object](#response-offerings-source) | Yes | App or integration supplying the voice capability. |
| `revision` | string | Yes | Revision identifying the version of this capability or configuration. |
| `source_version` | string | Yes | Published source version used by this capability. |
| `capability` | [object](#response-offerings-capability) | Yes | Voice capability exposed by an app or integration. |
| `available` | boolean | Yes | Whether this voice capability is available for the selected inbox. Allowed: `false`, `true`. |
| `reason` | string | No | Explanation of why this outcome occurred. |
| `follows_deploy` | boolean | No | Whether this binding follows new deployments of its source capability. Allowed: `true`. |

### response.offerings[].source

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `kind` | string | Yes | Category identifying which variant of this model applies. Allowed: `"app"`, `"builtin"`, `"integration"`. |
| `id` | string | Yes | Unique identifier. Use the value returned by a create or list operation. |
| `label` | string | Yes | Human-readable label shown for this item; use its ID or key in API calls. |

### response.offerings[].capability

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `kind` | string | Yes | Category identifying which variant of this model applies. Allowed: `"read"`, `"write"`. |
| `label` | string | Yes | Human-readable label shown for this item; use its ID or key in API calls. |
| `description` | string | Yes | Descriptive text. |
| `id` | string | Yes | Unique identifier. Use the value returned by a create or list operation. |
| `changes` | map of [object (3 variants)](#response-offerings-capability-changes) | Yes | Setting changes to apply to the existing binding. |
| `input` | map of JSON values | No | A JSON Schema document describing the accepted value. See https://json-schema.org/understanding-json-schema/. |
| `source` | string | No | App or integration supplying the voice capability. |
| `settings` | [object](#response-offerings-capability-settings) | No | Configuration fields defined by this voice capability. |
| `target` | [object](#response-offerings-capability-target) | No | Record or operation targeted by this capability. |
| `builtin` | string | No | Whether the capability is supplied by Brigg. Allowed: `"take_message"`, `"book_meeting"`, `"manage_calendar"`, `"search_knowledge"`, `"transfer_call"`, `"end_call"`. |

### response.offerings[].capability.changes.*

#### Variant 1

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `value` | null or string or number or boolean | Yes | Literal value to write when this capability applies the change. |

#### Variant 2

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `fromField` | string | Yes | Read the change value from this field on the selected record. |

#### Variant 3

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `fromInput` | string | Yes | Read the change value from this named capability input. |

### response.offerings[].capability.settings

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `booking_link_id` | string | No | Booking link identifier. |

### response.offerings[].capability.target

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `where` | map of null or string or number or boolean or [object](#response-offerings-capability-target-where) | Yes | Record-selection conditions used by the capability. |
| `type` | string | Yes | Type identifying which variant of this model applies. |
| `fields` | array of string | Yes | Named fields applicable to this item. |
| `bundle_id` | string | Yes | Bundle identifier. |
| `owner_field` | string | Yes | Field identifying the capability's owning record. |
| `owner_type` | string | Yes | Resource type of the capability's owning record. Allowed: `"company"`, `"person"`. |

### response.offerings[].capability.target.where.*

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `fromInput` | string | Yes | Read the change value from this named capability input. |

### response.bindings[]

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | Yes | Unique identifier. Use the value returned by a create or list operation. |
| `inbox_id` | string | Yes | Inbox identifier. |
| `offering_key` | string | Yes | Stable key identifying a published voice capability. |
| `revision` | string | Yes | Revision identifying the version of this capability or configuration. |
| `enabled` | boolean | Yes | Whether this feature is enabled. |
| `settings` | [VoiceBindingSettings](#voicebindingsettings-response-bindings-settings) | No | Configuration fields defined by this voice capability. |

### VoiceBindingSettings · response.bindings[].settings

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `booking_link_id` | string | No | Booking link identifier. |

### response.meetings[]

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | Yes | Unique identifier. Use the value returned by a create or list operation. |
| `label` | string | Yes | Human-readable label shown for this item; use its ID or key in API calls. |
| `owner` | string | Yes | Record to which the voice capability belongs. |

## Errors & retries

This operation reads data. It needs no idempotency key and can be retried after a transient failure.

For rate limits, follow the server’s retry guidance and back off. See [HTTP errors](https://developer.brigg.app/http#errors) and [safe retries and limits](https://developer.brigg.app/reliability).

| HTTP status | Code | What to do |
| --- | --- | --- |
| 400 | `invalid_json` | Send a JSON object with Content-Type: application/json. |
| 400 | `invalid_input` | Check the request fields and types. |
| 401 | `invalid_key` | The workspace API key is missing, invalid or revoked. |
| 403 | `forbidden` | Check the key’s operation and resource grants. If Brigg-Act-As is supplied, the key must be authorized to delegate to that member. |
| 404 | `not_found` | The requested operation or resource is not available to this credential. |
| 429 | `rate_limited` | Wait for Retry-After before retrying. |

## Next steps

- [Start voice test](https://developer.brigg.app/reference/voice/StartVoiceTest)
- [Update voice binding](https://developer.brigg.app/reference/voice/UpdateVoiceBinding)

[Download OpenAPI](https://developer.brigg.app/openapi.json) · [Versioning & retirement](https://developer.brigg.app/versioning)

## Examples

### Available booking capability

Use the offering key and revision with a valid meeting link. Existing bindings identify what the inbox currently has enabled.
#### cURL


```sh
curl 'https://api.brigg.app/v1/operations/voice.GetVoiceCatalog' \
  -H "Authorization: Bearer $BRIGG_API_KEY" \
  -H 'Content-Type: application/json' \
  --data-raw '{}'
```

#### TypeScript


```typescript
const response = await fetch("https://api.brigg.app/v1/operations/voice.GetVoiceCatalog", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.BRIGG_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({}),
});
const result = await response.json();
if (!response.ok) throw new Error(`${response.status}: ${result.error} — ${result.message}`);
console.log(result);
```

#### Python


```python
import json
import os
from urllib.request import Request, urlopen
from urllib.error import HTTPError

payload = {}
request = Request(
    "https://api.brigg.app/v1/operations/voice.GetVoiceCatalog",
    data=json.dumps(payload).encode("utf-8"),
    headers={
        "Authorization": f"Bearer {os.environ['BRIGG_API_KEY']}",
        "Content-Type": "application/json",
    },
    method="POST",
)
try:
    with urlopen(request) as response:
        print(json.load(response))
except HTTPError as error:
    print(error.code, json.load(error))
    raise
```

#### Response example


```json
{
  "offerings": [
    {
      "key": "[\"builtin\",\"brigg\",\"book_meeting\"]",
      "source": {
        "kind": "builtin",
        "id": "brigg",
        "label": "Brigg"
      },
      "revision": "revision_booking_1",
      "source_version": "1",
      "capability": {
        "kind": "write",
        "label": "Book a meeting",
        "description": "Book a time using an active meeting link.",
        "id": "book_meeting",
        "changes": {},
        "builtin": "book_meeting"
      },
      "available": true
    }
  ],
  "bindings": [
    {
      "id": "voice_binding_booking",
      "inbox_id": "e_inbox_support",
      "offering_key": "[\"builtin\",\"brigg\",\"book_meeting\"]",
      "revision": "revision_booking_1",
      "enabled": true,
      "settings": {
        "booking_link_id": "booking_support"
      }
    }
  ],
  "meetings": [
    {
      "id": "booking_support",
      "label": "Support consultation",
      "owner": "Alex Morgan"
    }
  ]
}
```

## JSON schemas


```json-schema-request
{
  "type": "object",
  "properties": {},
  "additionalProperties": false,
  "examples": [
    {}
  ]
}
```


```json-schema-response
{
  "type": "object",
  "properties": {
    "offerings": {
      "type": "array",
      "items": {
        "title": "VoiceOffering",
        "type": "object",
        "properties": {
          "key": {
            "type": "string",
            "description": "Stable key identifying this option within its collection; distinct from its display label."
          },
          "source": {
            "type": "object",
            "properties": {
              "kind": {
                "type": "string",
                "enum": [
                  "app",
                  "builtin",
                  "integration"
                ],
                "description": "Category identifying which variant of this model applies."
              },
              "id": {
                "type": "string",
                "description": "Unique identifier. Use the value returned by a create or list operation."
              },
              "label": {
                "type": "string",
                "description": "Human-readable label shown for this item; use its ID or key in API calls."
              }
            },
            "required": [
              "kind",
              "id",
              "label"
            ],
            "additionalProperties": false,
            "description": "App or integration supplying the voice capability."
          },
          "revision": {
            "type": "string",
            "description": "Revision identifying the version of this capability or configuration."
          },
          "source_version": {
            "type": "string",
            "description": "Published source version used by this capability."
          },
          "capability": {
            "type": "object",
            "properties": {
              "kind": {
                "type": "string",
                "enum": [
                  "read",
                  "write"
                ],
                "description": "Category identifying which variant of this model applies."
              },
              "label": {
                "type": "string",
                "description": "Human-readable label shown for this item; use its ID or key in API calls."
              },
              "description": {
                "type": "string",
                "description": "Descriptive text."
              },
              "id": {
                "type": "string",
                "description": "Unique identifier. Use the value returned by a create or list operation."
              },
              "changes": {
                "type": "object",
                "additionalProperties": {
                  "anyOf": [
                    {
                      "type": "object",
                      "properties": {
                        "value": {
                          "anyOf": [
                            {
                              "type": "null"
                            },
                            {
                              "type": "string"
                            },
                            {
                              "type": "number"
                            },
                            {
                              "type": "boolean",
                              "const": false
                            },
                            {
                              "type": "boolean",
                              "const": true
                            }
                          ],
                          "description": "Literal value to write when this capability applies the change."
                        }
                      },
                      "required": [
                        "value"
                      ],
                      "additionalProperties": false
                    },
                    {
                      "type": "object",
                      "properties": {
                        "fromField": {
                          "type": "string",
                          "description": "Read the change value from this field on the selected record."
                        }
                      },
                      "required": [
                        "fromField"
                      ],
                      "additionalProperties": false
                    },
                    {
                      "type": "object",
                      "properties": {
                        "fromInput": {
                          "type": "string",
                          "description": "Read the change value from this named capability input."
                        }
                      },
                      "required": [
                        "fromInput"
                      ],
                      "additionalProperties": false
                    }
                  ]
                },
                "description": "Setting changes to apply to the existing binding."
              },
              "input": {
                "type": "object",
                "additionalProperties": true,
                "description": "A JSON Schema document describing the accepted value. See https://json-schema.org/understanding-json-schema/."
              },
              "source": {
                "type": "string",
                "description": "App or integration supplying the voice capability."
              },
              "settings": {
                "type": "object",
                "properties": {
                  "booking_link_id": {
                    "type": "string",
                    "description": "Booking link identifier."
                  }
                },
                "required": [],
                "additionalProperties": false,
                "description": "Configuration fields defined by this voice capability."
              },
              "target": {
                "type": "object",
                "properties": {
                  "where": {
                    "type": "object",
                    "additionalProperties": {
                      "anyOf": [
                        {
                          "type": "null"
                        },
                        {
                          "type": "string"
                        },
                        {
                          "type": "number"
                        },
                        {
                          "type": "boolean",
                          "const": false
                        },
                        {
                          "type": "boolean",
                          "const": true
                        },
                        {
                          "type": "object",
                          "properties": {
                            "fromInput": {
                              "type": "string",
                              "description": "Read the change value from this named capability input."
                            }
                          },
                          "required": [
                            "fromInput"
                          ],
                          "additionalProperties": false
                        }
                      ]
                    },
                    "description": "Record-selection conditions used by the capability."
                  },
                  "type": {
                    "type": "string",
                    "description": "Type identifying which variant of this model applies."
                  },
                  "fields": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "Named fields applicable to this item."
                  },
                  "bundle_id": {
                    "type": "string",
                    "description": "Bundle identifier."
                  },
                  "owner_field": {
                    "type": "string",
                    "description": "Field identifying the capability's owning record."
                  },
                  "owner_type": {
                    "type": "string",
                    "enum": [
                      "company",
                      "person"
                    ],
                    "description": "Resource type of the capability's owning record."
                  }
                },
                "required": [
                  "where",
                  "type",
                  "fields",
                  "bundle_id",
                  "owner_field",
                  "owner_type"
                ],
                "additionalProperties": false,
                "description": "Record or operation targeted by this capability."
              },
              "builtin": {
                "type": "string",
                "enum": [
                  "take_message",
                  "book_meeting",
                  "manage_calendar",
                  "search_knowledge",
                  "transfer_call",
                  "end_call"
                ],
                "description": "Whether the capability is supplied by Brigg."
              }
            },
            "required": [
              "kind",
              "label",
              "description",
              "id",
              "changes"
            ],
            "additionalProperties": false,
            "description": "Voice capability exposed by an app or integration."
          },
          "available": {
            "type": "boolean",
            "enum": [
              false,
              true
            ],
            "description": "Whether this voice capability is available for the selected inbox."
          },
          "reason": {
            "type": "string",
            "description": "Explanation of why this outcome occurred."
          },
          "follows_deploy": {
            "type": "boolean",
            "enum": [
              true
            ],
            "description": "Whether this binding follows new deployments of its source capability."
          }
        },
        "required": [
          "key",
          "source",
          "revision",
          "source_version",
          "capability",
          "available"
        ],
        "additionalProperties": false
      },
      "description": "Available voice capabilities that can be bound to an inbox assistant."
    },
    "bindings": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "Unique identifier. Use the value returned by a create or list operation."
          },
          "inbox_id": {
            "type": "string",
            "description": "Inbox identifier."
          },
          "offering_key": {
            "type": "string",
            "description": "Stable key identifying a published voice capability."
          },
          "revision": {
            "type": "string",
            "description": "Revision identifying the version of this capability or configuration."
          },
          "enabled": {
            "type": "boolean",
            "description": "Whether this feature is enabled."
          },
          "settings": {
            "description": "Configuration fields defined by this voice capability.",
            "title": "VoiceBindingSettings",
            "type": "object",
            "properties": {
              "booking_link_id": {
                "type": "string",
                "description": "Booking link identifier."
              }
            },
            "required": [],
            "additionalProperties": false
          }
        },
        "required": [
          "id",
          "inbox_id",
          "offering_key",
          "revision",
          "enabled"
        ],
        "additionalProperties": false
      },
      "description": "Configured connections between an inbox assistant and voice capabilities."
    },
    "meetings": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "Unique identifier. Use the value returned by a create or list operation."
          },
          "label": {
            "type": "string",
            "description": "Human-readable label shown for this item; use its ID or key in API calls."
          },
          "owner": {
            "type": "string",
            "description": "Record to which the voice capability belongs."
          }
        },
        "required": [
          "id",
          "label",
          "owner"
        ],
        "additionalProperties": false
      },
      "description": "Booking links available to the voice assistant."
    }
  },
  "required": [
    "offerings",
    "bindings",
    "meetings"
  ],
  "additionalProperties": false,
  "examples": [
    {
      "offerings": [
        {
          "key": "[\"builtin\",\"brigg\",\"book_meeting\"]",
          "source": {
            "kind": "builtin",
            "id": "brigg",
            "label": "Brigg"
          },
          "revision": "revision_booking_1",
          "source_version": "1",
          "capability": {
            "kind": "write",
            "label": "Book a meeting",
            "description": "Book a time using an active meeting link.",
            "id": "book_meeting",
            "changes": {},
            "builtin": "book_meeting"
          },
          "available": true
        }
      ],
      "bindings": [
        {
          "id": "voice_binding_booking",
          "inbox_id": "e_inbox_support",
          "offering_key": "[\"builtin\",\"brigg\",\"book_meeting\"]",
          "revision": "revision_booking_1",
          "enabled": true,
          "settings": {
            "booking_link_id": "booking_support"
          }
        }
      ],
      "meetings": [
        {
          "id": "booking_support",
          "label": "Support consultation",
          "owner": "Alex Morgan"
        }
      ]
    }
  ]
}
```