Add voice binding — Brigg developers

Access & visibility

Allow voice.AddVoiceBinding on your API key.

Acting member required. Send Brigg-Act-As with an approved member account ID. The key supplies permissions; the member selects whose data is used.

The selected member must be active and approved by the credential. This selects whose private data is used; the credential supplies permissions. Private ownership and project boundaries still apply.

Set up authentication · Choose permissions

Request fields

Send a JSON object with the following fields. Required fields must be included; omit optional fields you do not need.

inbox_idstringRequired

Inbox ID from ListInboxes, or the original inbox_id of an existing binding. Updating cannot move a binding to another inbox.

At least 1 character.

offering_keystringRequired

Exact key from GetVoiceCatalog.offerings. Treat it as an opaque string; do not build it from a capability label.

At least 1 character.

revisionstringRequired

Revision from the selected offering, reviewed before enabling it. A changed revision is refused with HTTP 409; re-read the catalogue and review the change.

At least 1 character.

settingsobjectRequired

Complete settings for this offering. For meeting booking, supply booking_link_id from the catalogue's meetings. Updating replaces settings rather than merging individual keys.

Nested fields

booking_link_idstringOptional

Active booking link ID from GetVoiceCatalog.meetings. Required by the built-in meeting-booking offering; links requiring unsupported extra questions cannot be used for phone booking.

enabledbooleanRequired

Whether this feature is enabled.

Bind a capability to an inbox

Get voice catalogue 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. 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 after changing its capabilities.

Response

Returns 200 OK with a JSON body.

idstringRequired

Binding ID to retain for updates and removal.

inbox_idstringRequired

Inbox to which this binding belongs. It is the request's inbox_id.

offering_keystringRequired

Stable key identifying a published voice capability.

revisionstringRequired

Revision identifying the version of this capability or configuration.

enabledbooleanRequired

Whether this binding is enabled. The offering's availability and revision are checked when enabling it.

settingsVoiceBindingSettingsOptional

Configuration fields defined by this voice capability.

VoiceBindingSettings

booking_link_idstringOptional

Active booking link selected for this inbox's meeting-booking capability.

Errors & retries

Set BRIGG_REQUEST_ID once for each logical action. The samples send it as Idempotency-Key. Reuse the same value and body on retries, including after a timeout; a missing response does not prove the action failed.

For rate limits, follow the server’s retry guidance and back off. See HTTP errors and safe retries and limits.

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. Supply a stable Idempotency-Key containing 1–200 characters.
401	`invalid_key`	The workspace API key is missing, invalid or revoked.
403	`forbidden`	Check the key’s operation and resource grants. Supply Brigg-Act-As with a member authorized by the key’s delegation grant. The selected member must be active and approved by the credential. This selects whose private data is used; the credential supplies permissions. Private ownership and project boundaries still apply.
404	`not_found`	The requested operation or resource is not available to this credential.
429	`rate_limited`	Wait for Retry-After before retrying. Reuse the original Idempotency-Key.

Next steps

Download OpenAPI · Versioning & retirement

JSON schemas

Use the complete schemas for validation or client generation.

Full request JSON schema

{
  "type": "object",
  "properties": {
    "inbox_id": {
      "type": "string",
      "minLength": 1,
      "description": "Inbox ID from ListInboxes, or the original inbox_id of an existing binding. Updating cannot move a binding to another inbox."
    },
    "offering_key": {
      "type": "string",
      "minLength": 1,
      "description": "Exact key from GetVoiceCatalog.offerings. Treat it as an opaque string; do not build it from a capability label."
    },
    "revision": {
      "type": "string",
      "minLength": 1,
      "description": "Revision from the selected offering, reviewed before enabling it. A changed revision is refused with HTTP 409; re-read the catalogue and review the change."
    },
    "settings": {
      "type": "object",
      "properties": {
        "booking_link_id": {
          "type": "string",
          "description": "Active booking link ID from GetVoiceCatalog.meetings. Required by the built-in meeting-booking offering; links requiring unsupported extra questions cannot be used for phone booking."
        }
      },
      "additionalProperties": false,
      "description": "Complete settings for this offering. For meeting booking, supply booking_link_id from the catalogue's meetings. Updating replaces settings rather than merging individual keys."
    },
    "enabled": {
      "type": "boolean",
      "description": "Whether this feature is enabled."
    }
  },
  "required": [
    "inbox_id",
    "offering_key",
    "revision",
    "settings",
    "enabled"
  ],
  "additionalProperties": false,
  "examples": [
    {
      "inbox_id": "e_inbox_support",
      "offering_key": "[\"builtin\",\"brigg\",\"book_meeting\"]",
      "revision": "revision_booking_1",
      "enabled": true,
      "settings": {
        "booking_link_id": "booking_support"
      }
    }
  ]
}

Full response JSON schema

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "Binding ID to retain for updates and removal."
    },
    "inbox_id": {
      "type": "string",
      "description": "Inbox to which this binding belongs. It is the request's inbox_id."
    },
    "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 binding is enabled. The offering's availability and revision are checked when enabling it."
    },
    "settings": {
      "description": "Configuration fields defined by this voice capability.",
      "title": "VoiceBindingSettings",
      "type": "object",
      "properties": {
        "booking_link_id": {
          "type": "string",
          "description": "Active booking link selected for this inbox's meeting-booking capability."
        }
      },
      "required": [],
      "additionalProperties": false
    }
  },
  "required": [
    "id",
    "inbox_id",
    "offering_key",
    "revision",
    "enabled"
  ],
  "additionalProperties": false,
  "examples": [
    {
      "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"
      }
    }
  ]
}

Try the request

Use your API key in a server environment.

Requires BRIGG_ACT_AS: an approved member account ID.

Read the current catalogue and substitute its exact offering key, revision, meeting link and inbox IDs. These example identifiers are fictional.

Request

cURL

curl 'https://api.brigg.app/v1/operations/voice.AddVoiceBinding' \
  -H "Authorization: Bearer $BRIGG_API_KEY" \
  -H 'Content-Type: application/json' \
  -H "Brigg-Act-As: $BRIGG_ACT_AS" \
  -H "Idempotency-Key: $BRIGG_REQUEST_ID" \
  --data-raw '{
  "inbox_id": "e_inbox_support",
  "offering_key": "[\"builtin\",\"brigg\",\"book_meeting\"]",
  "revision": "revision_booking_1",
  "enabled": true,
  "settings": {
    "booking_link_id": "booking_support"
  }
}'

TypeScript

const actAs = process.env.BRIGG_ACT_AS;
if (!actAs) throw new Error("Set BRIGG_ACT_AS to an approved member account ID.");

const requestId = process.env.BRIGG_REQUEST_ID;
if (!requestId) throw new Error("Set BRIGG_REQUEST_ID once per action and reuse it on retries.");

const response = await fetch("https://api.brigg.app/v1/operations/voice.AddVoiceBinding", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.BRIGG_API_KEY}`,
    "Content-Type": "application/json",
    "Brigg-Act-As": actAs,
    "Idempotency-Key": requestId, // Create once per action; reuse on retries.
  },
  body: JSON.stringify({
    "inbox_id": "e_inbox_support",
    "offering_key": "[\"builtin\",\"brigg\",\"book_meeting\"]",
    "revision": "revision_booking_1",
    "enabled": true,
    "settings": {
      "booking_link_id": "booking_support"
    }
  }),
});
const result = await response.json();
if (!response.ok) throw new Error(`${response.status}: ${result.error} — ${result.message}`);
console.log(result);

Python

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

request_id = os.environ["BRIGG_REQUEST_ID"]  # Reuse for retries of this action.
payload = {
  "inbox_id": "e_inbox_support",
  "offering_key": "[\"builtin\",\"brigg\",\"book_meeting\"]",
  "revision": "revision_booking_1",
  "enabled": True,
  "settings": {
    "booking_link_id": "booking_support"
  }
}
request = Request(
    "https://api.brigg.app/v1/operations/voice.AddVoiceBinding",
    data=json.dumps(payload).encode("utf-8"),
    headers={
        "Authorization": f"Bearer {os.environ['BRIGG_API_KEY']}",
        "Content-Type": "application/json",
        "Brigg-Act-As": os.environ["BRIGG_ACT_AS"],
        "Idempotency-Key": request_id,  # Create once per action; reuse on retries.
    },
    method="POST",
)
try:
    with urlopen(request) as response:
        print(json.load(response))
except HTTPError as error:
    print(error.code, json.load(error))
    raise

200 OK Response example

{
  "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"
  }
}

Illustrative values, not a live response.