Chat Accounts

Accounts are the companies your customers belong to, such as a workspace, team or tenant in your product. When conversations and tickets are filed under an account, your team can see everything from one company in one place, and your own app can show a company its tickets.

Accounts are added in three ways: your website sends a signed company when a signed-in customer opens the messenger, a teammate adds or imports them on the Accounts page, or your app syncs them through the API.

Send the company from your website

Pass company and company_hash in the messenger settings, alongside the signed-in customer's details. The company is accepted only for a customer verified with user_hash, so set up identity verification first. Without a valid hash the company is ignored, and the messenger still loads normally.

window.DocentSettings = { app_id: "YOUR_APP_ID", user_id: "12345", email: "[email protected]", name: "Jane Doe", user_hash: "USER_HASH_FROM_YOUR_SERVER", company: { id: "acme-42", // your id for the company (required) name: "Acme Corp", // optional plan: "Growth" // any other fields are kept as details }, company_hash: "COMPANY_HASH_FROM_YOUR_SERVER" };

If your site switches the signed-in customer to another company, call Docent('update', { company: {...}, company_hash: "..." }) and the messenger picks up the new account. See the Chat Messenger JavaScript API.

Compute the company_hash on your server

The company_hash is made the same way as user_hash: an HMAC-SHA256 with your messenger's Identity secret, written as lowercase hex. What you sign is the user's id, a | character, and the company id. For user 12345 in company acme-42, sign 12345|acme-42. (If you verify customers by email instead of a user id, sign the email in place of the user id.)

LanguageCode
Node.jscrypto.createHmac('sha256', SECRET).update(user.id + '|' + company.id).digest('hex')
C#Convert.ToHexString(new HMACSHA256(Encoding.UTF8.GetBytes(SECRET)).ComputeHash(Encoding.UTF8.GetBytes(user.Id + "|" + company.Id))).ToLowerInvariant()
PHPhash_hmac('sha256', $user->id . '|' . $company->id, $SECRET)
Pythonhmac.new(SECRET.encode(), (user.id + '|' + company.id).encode(), hashlib.sha256).hexdigest()
Keep the secret on your server

Never put the identity secret in browser code. Because the hash covers both the user and the company, a hash copied from one customer's page can't put someone else into that company.

The Accounts page

Open your messenger and choose Accounts in its sidebar. Everyone who works the inbox can look at it; adding, renaming, deleting and importing need an Owner or Admin.

The list is in name order and shows each account's Open and total Conversations, its People and when it was Last seen, with its id and details underneath. Use Search by name or ID… to find one. Accounts added here, imported or synced are marked Managed and are kept even before anyone from them writes in. Click an account's name to open the inbox showing only that account.

Import a CSV file

Click Import CSV and choose a file (up to 3 MB). The first row names the columns: id (required), name, and any others, which are kept as the account's details (up to 20). An account that's already there is updated, and its details are replaced by the file's. When it finishes you see how many were added and updated, and which lines were skipped and why.

id,name,plan acme-42,Acme Corp,Growth globex,Globex,Starter

Accounts in the inbox

Once you have accounts, the inbox shows each conversation's account under it in the list, and adds an account button (the building icon, Show one account) beside the search box. Pick an account to list only its conversations and tickets, in every view, until you clear it with the ✕ on the bar above the list. In the ticket table, the Account filter does the same; see Working with Tickets.

The Account row in a conversation's right-hand panel shows its account and how many open conversations that account has. Click ↗ to see all of that account's conversations (or tickets, with ticketing on).

Move a conversation to another account

Click the account name in the Account row (or + Add to account when it has none) to open File under an account, then pick one. You can also choose Take it out of its current account. Only that conversation moves: a signed-in customer stays in the account your website says they're in, so their next conversation is filed there again.

Emails and accounts

An email is filed under an account only when the sender's address is verified (the email passed the sender's own domain checks) and matches a signed-in customer you've verified, who belongs to that account. An email that can't be verified is never filed under anyone's account automatically, so nobody can reach a company's tickets by faking a From address. See the email channel. When you create a ticket yourself with New ticket, you can choose its account.

For developers: the accounts and tickets APIs

Your app can keep accounts in step and show each company its own tickets, using an API key. Create keys on the Developers page in the account sidebar; see API Keys and the REST API. These APIs work at the messenger level, so use a key that works on every project, not one limited to a single project. Send the key as Authorization: Bearer <API key>. {messenger} is your messenger's app id, and {id} is your id for the account.

Sync accounts

RequestPermissionWhat it does
GET /api/v1/messengers/{messenger}/accounts?q=&skip=&take=project:read or project:writeLists accounts, optionally matching q (up to 200 a page).
POST /api/v1/messengers/{messenger}/accountsproject:writeAdds or updates up to 500 accounts by your id. Returns how many were created and updated, and any that were skipped.
DELETE /api/v1/messengers/{messenger}/accounts/{id}project:writeDeletes an account. Its people and conversations are kept.
POST https://trydocent.ai/api/v1/messengers/{messenger}/accounts Authorization: Bearer <API key> Content-Type: application/json { "accounts": [ { "id": "acme-42", "name": "Acme Corp", "attributes": { "plan": "Growth" } } ] }

Send every account once, then each one when it's added or renamed. Leaving out name or attributes keeps what's stored. The exact address, with your messenger's id filled in, is shown at the bottom of the Accounts page.

Tickets for an account

Show a company its tickets inside your own app. Every request is limited to the account in the address: a ticket that belongs to another account answers "not found". Only what the customer saw is returned, never internal notes or your team's ticket fields.

RequestPermissionWhat it does
GET /api/v1/messengers/{messenger}/accounts/{id}/tickets?status=&skip=&take=chat:readLists the account's tickets, most recently active first (up to 200 a page). status is active (open, pending or on hold; the default), open, pending, hold, solved, closed or any.
GET …/accounts/{id}/tickets/{number}chat:readOne ticket (for #1042, use 1042) with its messages.
POST …/accounts/{id}/tickets/{number}/messageschat:writeAdds a message from the customer: body (text) or html, and author with name and email of the person writing. Your team is alerted as for any customer reply, and a Pending, Solved or Closed ticket goes back to Open.
POST …/accounts/{id}/tickets/{number}/reopenchat:writeReopens a Pending, Solved or Closed ticket. Send author so the ticket's history says who reopened it.
POST https://trydocent.ai/api/v1/messengers/{messenger}/accounts/acme-42/tickets/1042/messages Authorization: Bearer <API key> Content-Type: application/json { "body": "This is still happening after the update.", "author": { "name": "Jane Doe", "email": "[email protected]" } }