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.
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.
id is required: your own id for the company, up to 256 characters, without a | character.name is optional. It's what your team sees; without one, the id is shown.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.
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.)
| Language | Code |
|---|---|
| Node.js | crypto.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() |
| PHP | hash_hmac('sha256', $user->id . '|' . $company->id, $SECRET) |
| Python | hmac.new(SECRET.encode(), (user.id + '|' + company.id).encode(), hashlib.sha256).hexdigest() |
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.
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.
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.
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).
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.
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.
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.
| Request | Permission | What it does |
|---|---|---|
GET /api/v1/messengers/{messenger}/accounts?q=&skip=&take= | project:read or project:write | Lists accounts, optionally matching q (up to 200 a page). |
POST /api/v1/messengers/{messenger}/accounts | project:write | Adds 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:write | Deletes an account. Its people and conversations are kept. |
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.
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.
| Request | Permission | What it does |
|---|---|---|
GET /api/v1/messengers/{messenger}/accounts/{id}/tickets?status=&skip=&take= | chat:read | Lists 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:read | One ticket (for #1042, use 1042) with its messages. |
POST …/accounts/{id}/tickets/{number}/messages | chat:write | Adds 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}/reopen | chat:write | Reopens a Pending, Solved or Closed ticket. Send author so the ticket's history says who reopened it. |