List & get contacts (v1)

GET /api/v1/chatbots/:chatbotId/contacts to list (paged) and GET /api/v1/chatbots/:chatbotId/contacts/:contactId to fetch one by external id.

View as Markdown

GET /api/v1/chatbots/:chatbotId/contacts

List contacts for an agent. Page-based pagination, returned in a pages object alongside the total. contactId in the single-get path is the contact's external_id.

Param	In	Type	Notes
chatbotId	path	integer	The agent id.
page	query	integer	Page number (default 1).
per_page	query	integer	Items per page. Clamped to 10–1000, default 100.

curl "https://app.bookbag.ai/api/v1/chatbots/123/contacts?page=1&per_page=50" \
  -H "Authorization: Bearer $BOOKBAG_API_KEY"

const res = await fetch(
  "https://app.bookbag.ai/api/v1/chatbots/123/contacts?page=1&per_page=50",
  { headers: { Authorization: `Bearer ${process.env.BOOKBAG_API_KEY}` } }
);
const { data, total, pages } = await res.json();

{
  "message": "Success",
  "data": [
    {
      "id": "contact_57",
      "external_id": "user_8821",
      "name": "Sam Rivera",
      "email": "sam@acme.com",
      "phonenumber": null,
      "stripe_accounts": [],
      "custom_attributes": { "plan": "pro" },
      "created_at": 1717286400,
      "updated_at": 1717286400
    }
  ],
  "total": 1,
  "pages": { "page": 1, "per_page": 50, "total_pages": 1 }
}

GET /api/v1/chatbots/:chatbotId/contacts/:contactId

Fetch a single contact by its external_id.

Param	In	Type	Notes
chatbotId	path	integer	The agent id.
contactId	path	string	The contact's `external_id`.

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

{
  "message": "Success",
  "data": {
    "id": "contact_57",
    "external_id": "user_8821",
    "name": "Sam Rivera",
    "email": "sam@acme.com",
    "phonenumber": null,
    "stripe_accounts": [],
    "custom_attributes": { "plan": "pro" },
    "created_at": 1717286400,
    "updated_at": 1717286400
  }
}

Status codes

Status	Meaning
200	Success.
401	Missing or invalid key.
404	Unknown chatbot/contact, or out of scope. Body: `{ message: "Resource not found" }`.

See Errors.

Create contacts

Update a contact