Custom attributes (v1)

List, create, and update the custom attribute definitions for an agent: GET/POST /api/v1/chatbots/:chatbotId/custom-attributes and PUT /:name.

View as Markdown

Custom attributes define the extra fields you can store on contacts (for example plan or ltv). These endpoints manage the definitions; the values live on each contact's custom_attributes object. All paths are authenticated with Authorization: Bearer oc_... and chatbotId is your agent id.

GET /api/v1/chatbots/:chatbotId/custom-attributes

List the attribute definitions for an agent.

curl https://app.bookbag.ai/api/v1/chatbots/123/custom-attributes \
  -H "Authorization: Bearer $BOOKBAG_API_KEY"

POST /api/v1/chatbots/:chatbotId/custom-attributes

Create an attribute definition.

Field	Type	Required	Notes
name	string	Yes	Must start with a letter; letters, numbers, underscores, hyphens only. Unique per agent.
label	string	No	Display label. Defaults to `name`.
type	string	No	One of `text`, `number`, `boolean`, `date`. Defaults to `text`.
description	string	No	Free-text help.
archived	boolean	No	Create it archived (hidden from the contact UI).

curl https://app.bookbag.ai/api/v1/chatbots/123/custom-attributes \
  -H "Authorization: Bearer $BOOKBAG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "ltv", "label": "Lifetime value", "type": "number" }'

PUT /api/v1/chatbots/:chatbotId/custom-attributes/:name

Update an attribute definition by name. You can change label, description, and archived. The name and type are fixed once created.

Field	In	Type	Notes
name	path	string	The attribute name.
label	body	string	New display label.
description	body	string	New description.
archived	body	boolean	Archive or unarchive.

curl -X PUT https://app.bookbag.ai/api/v1/chatbots/123/custom-attributes/ltv \
  -H "Authorization: Bearer $BOOKBAG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "label": "LTV (USD)", "archived": true }'

Status codes

Status	Meaning
200	Success.
400	Invalid `name` or `type`. Body: `{ message }` describing the rule.
401	Missing or invalid key.
404	Unknown chatbot/attribute. Body: `{ message: "Resource not found" }`.
409	An attribute with that name already exists. Body: `{ message: "Attribute already exists" }`.

See Errors.

Delete a contact

v2 overview