Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/jAtInn71/chatwoot-costom/llms.txt

Use this file to discover all available pages before exploring further.

The widget contact API provides endpoints under /api/v1/widget/contact for managing the visitor’s contact record during a widget session. These endpoints handle everything from reading the current contact’s profile to updating identity details and removing custom attributes. All endpoints in this group are called by the widget SDK. Unless you are building a custom integration, you will typically interact with this layer indirectly through the widget JavaScript API (for example, $chatwoot.setUser(...)) rather than calling these endpoints directly.

​
Authentication

Every endpoint requires website_token as a query parameter to identify the inbox. In addition, contact endpoints use a contact auth token sent as a request header. The token is issued by the server on first contact creation, stored in session storage by the widget, and cleared on chat exit. 
?website_token=YOUR_WEBSITE_TOKEN

​
Contact auth token flow

The widget uses a session-scoped token to associate subsequent requests with the same contact record:
  1. First visit — no token exists in session storage. The widget calls the contact creation endpoint to register a new contact and receives an auth token in the response.
  2. Subsequent requests — the token is read from session storage and sent as a header on every contact and conversation API call. This ties all activity during the session to the same contact.
  3. Chat exit (soft exit) — when a visitor ends the chat, the widget calls clearCurrentUser() which clears the auth token from session storage and removes it from the default request headers. The next visitor who opens the widget starts with no token and receives a fresh contact, keeping sessions isolated.
The website_token is captured once at module load time from the original iframe URL, before any window.history.replaceState() calls that strip session parameters during exit. This ensures contact API calls are never broken by URL mutations.

​
Show current contact

GET /api/v1/widget/contact
Returns the contact record for the current visitor. The widget uses this to hydrate the local contact state on load when a session token already exists in session storage. Returns the contact’s name, email, phone number, and any custom attributes that have been set.

​
Update contact

PATCH /api/v1/widget/contact
Updates the current contact’s profile fields or custom attributes. The widget calls this in two contexts:
  • When the visitor submits the pre-chat form (name, email, phone number)
  • When your application calls $chatwoot.setCustomAttributes(...) to attach metadata to the contact
Request body for profile update: 
{
  "name": "Jane Doe",
  "email": "jane@example.com",
  "phone_number": "+15550001234"
}
Request body for custom attributes: 
{
  "custom_attributes": {
    "plan": "pro",
    "account_id": "acct_12345"
  }
}

​
Set user identity

PATCH /api/v1/widget/contact/set_user
Associates the current anonymous widget contact with a known user in your application. This is the endpoint called when your application uses $chatwoot.setUser(identifier, { name, email, ... }). The identifier is a unique string from your application (typically a user ID). When HMAC identity verification is enabled on the inbox, you must also pass a hmac_token computed server-side from the identifier and the inbox’s HMAC secret. Request body: 
{
  "identifier": "user_abc123",
  "name": "Jane Doe",
  "email": "jane@example.com",
  "phone_number": "+15550001234",
  "hmac_token": "<optional HMAC signature>"
}

​
Remove custom attributes

POST /api/v1/widget/contact/destroy_custom_attributes
Removes one or more custom attributes from the current contact record. Use this when a previously set attribute is no longer relevant — for example, after a trial period ends and the contact’s plan attribute should be cleared. Request body: 
{
  "custom_attributes": ["plan", "trial_end_date"]
}
Returns HTTP 200 on success.

​
Notes

If you use $chatwoot.setUser(...) in your application, call it as early as possible after the widget loads. The contact auth token is tied to the anonymous visitor record until set_user is called, after which subsequent requests are linked to the identified user.
Do not call destroy_custom_attributes to remove all attributes at the end of a session — the contact record persists across sessions for identified users. The soft exit flow clears the local session token, but the contact record and its attributes remain on the server for future reference by agents.

Build docs developers (and LLMs) love

Get started for freeTalk to us