Skip to main content

​
Users

Three types of users can participate in a chat:

Agents

The people on your team. When an agent joins a chat through the Text interface or via the API, they become a participant. Their messages are events.

Customers

The people your team talks to. A customer starts a chat and sends messages. They can have custom properties attached — like their order ID or account tier.

Bots

Automated participants that act on the agent side. A bot can send messages, close chats, and handle routing — just like a human agent, but programmatically.
Bots are created through the Configuration API. Once you’ve created one, use the Issue Bot Token method to get a token for it, then pass that token as a Bearer token — the same way you’d use a human agent’s access token. At the protocol level, the Agent Chat API treats bots and agents identically.

​
Teams

Teams group agents for routing — determining who handles an incoming chat or ticket. The two team types are independent of each other:
  • Chatting teams — handle live chat conversations, managed through the Configuration API.
  • Ticketing teams — handle tickets, managed through the Ticketing API.

​
Accounts

Text’s identity layer is called Global Accounts. It’s the system that manages accounts and organizations across the platform, and it’s exposed through the Global Accounts API. An account is a single identity — one person, one set of credentials — that can access Text. Every account has a unique ID. When your code makes an API call, it’s always acting as a specific account — the one that owns the token being used.
Every account has a unique account_id (a UUID) that appears in every token response and authorization-related API call.To look up the account tied to the current token, call GET /accounts/me — me resolves to whoever owns the token making the request.

​
Organizations

An organization is the workspace that holds a team together. Think of it as the equivalent of what you see in Text as “your company” — the thing with the agents, chats, and settings. A few things to know:
  • Every organization has at least one account, and at least one owner.
  • An account can belong to multiple organizations at once. A consultant working across several client accounts, for example, has one login but can switch between organizations.
  • Each account has a default organization — the one it lands on at login.
  • Organizations track which Text products are installed on them.
Every organization has an organization_id (a UUID). Both account_id and organization_id are included in every OAuth token response, so you always know which account and organization a token belongs to.Two endpoints are worth knowing: GET /organizations/my returns the organization tied to the current token, and GET /info introspects the token itself — returning its scopes, expiry, account_id, and organization_id.Organizations also have an invitation mode. The default, lax, lets all paid roles send invitations. Set it to strict to limit that to privileged roles only.

​
Why this matters for integrations

When you use a personal access token, it’s tied to your account and implicitly scoped to your default organization. Simple. When you build an OAuth integration — one where other users authorize your app — the token you receive represents a specific account acting within a specific organization. Both are part of every authorization response.
If you’re using a personal access token for a personal script or internal tool, you don’t need to think about this much. This becomes important when you’re building for other users.
If your app serves multiple Text customers, don’t use account_id alone as the key for a workspace context — an account can belong to more than one organization. Store (account_id, organization_id) pairs instead.When issuing a customer access token through the cookie grant flow, organization_id is required — the auth server needs it to know which organization the customer belongs to.POST /organizations creates both a new organization and an account in a single call, and doesn’t send any email notifications.