Update a contact (v1)

PATCH /api/v1/chatbots/:chatbotId/contacts/:contactId — update a contact by external id. Accepts a Chatbase-style { data: {...} } wrapper or a bare body.

View as Markdown

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

Update an existing contact, addressed by its external_id. Only the fields you send are changed. Sending null for name, email, or phonenumber clears it. For Chatbase compatibility the body may be wrapped in { "data": { ... } }, or sent bare.

Auth & ids

Authenticate with Authorization: Bearer bk_.... chatbotId is your agent id; contactId is the contact's external_id.

Path & body

Field	In	Type	Notes
chatbotId	path	integer	The agent id.
contactId	path	string	The contact's current `external_id`.
external_id	body	string	Change the external id. Must be unique for the agent or you get `409`.
name	body	string\|null	New name, or `null` to clear.
email	body	string\|null	New email, or `null` to clear.
phonenumber	body	string\|null	New phone, or `null` to clear.
stripe_accounts	body	array	Replaces the array.
custom_attributes	body	object	Replaces the custom-attributes object.

curl -X PATCH https://app.bookbag.ai/api/v1/chatbots/123/contacts/user_8821 \
  -H "Authorization: Bearer $BOOKBAG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "data": { "name": "Sam R.", "custom_attributes": { "plan": "enterprise" } } }'

const res = await fetch(
  "https://app.bookbag.ai/api/v1/chatbots/123/contacts/user_8821",
  {
    method: "PATCH",
    headers: {
      Authorization: `Bearer ${process.env.BOOKBAG_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ data: { name: "Sam R." } }),
  }
);
const { data } = await res.json();

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

Status codes

Status	Meaning
200	Updated.
401	Missing or invalid key.
404	Unknown chatbot/contact. Body: `{ message: "Resource not found" }`.
409	New `external_id` conflicts. Body: `{ message: "Error saving chatbot contact. External ID or email already exists." }`.

See Errors.

List contacts

Delete a contact