An agency runs WhatsApp for twelve shops: one organization, with a workspace for each shop. A workspace holds one WhatsApp connection with its contacts, conversations, message templates, and automations. Karim, who owns the garage, wants to answer his own customers, without seeing the customers of the eleven other shops.
Who sees which workspace?
A member's access is admin or member:
An administrator of the organization administers every workspace. Its creator becomes the first one, and it always keeps one.
A member works only in the workspaces it was given, with the role
adminormemberin each. Karim gets the garage's workspace, and nothing else reaches him: not the other shops' contacts, conversations, or notifications, nor the organization's members. A freelancer handling two shops gets those two.
What does an administrator do that a member cannot?
In a workspace, only its administrators connect WhatsApp, send a broadcast, and publish an automation version, since these message contacts. Every member works with its contacts, conversations, templates, and automations, and listWorkspaceMembers shows who else does.
Only an administrator of the organization renames or deletes it, manages its workspaces, invites people, reads its usage, and changes what each member works in with updateOrganizationMemberAccess.
How does a person join an organization?
An administrator invites their phone number, as an administrator or into chosen workspaces. Heythere sends no message, so tell Karim to sign in to Heythere with that number within 7 days, and he joins with the invited access.
What does a workspace's map show?
Every WhatsApp number of the workspace, each with its automation, the events it starts at, and its latest broadcasts, with how far each went. The console shows it on the automations page, and getWorkspaceMap returns it to an agent.
How does an agent choose an organization and a workspace?
An agent or API key acts as its user, and sees what that user sees. listOrganizations and then listOrganizationWorkspaces give the IDs that every other operation names in its path.
Deleting a workspace or an organization is permanent: it erases their contacts, conversations, messages, and automations.
In the API
Every operation is a REST endpoint and, unless marked REST only, an MCP tool of the same name. The OpenAPI document describes their parameters, payloads, and errors.
- POST
createOrganizationCreate an organization
/api/organizations - GET
listOrganizationsList joined organizations
/api/organizations - GET
getOrganizationGet an organization
/api/organizations/{organizationId} - PATCH
updateOrganizationUpdate an organization
/api/organizations/{organizationId} - DELETE
deleteOrganizationDelete an organization
/api/organizations/{organizationId} - GET
listOrganizationMembersList organization members
/api/organizations/{organizationId}/members - PUT
updateOrganizationMemberAccessReplace what an organization member works in
/api/organizations/{organizationId}/members/{memberId}/access - DELETE
removeOrganizationMemberRemove an organization member
/api/organizations/{organizationId}/members/{memberId} - POST
inviteOrganizationMemberInvite an organization member
/api/organizations/{organizationId}/invitations - GET
listOrganizationInvitationsList organization invitations
/api/organizations/{organizationId}/invitations - GET
getOrganizationInvitationGet an organization invitation
/api/organizations/{organizationId}/invitations/{invitationId} - DELETE
revokeOrganizationInvitationRevoke an organization invitation
/api/organizations/{organizationId}/invitations/{invitationId} - GET
listReceivedOrganizationInvitationsList received organization invitations
/api/organization-invitations - POST
acceptOrganizationInvitationAccept an organization invitation
/api/organization-invitations/{invitationId}/acceptance - DELETE
declineOrganizationInvitationDecline an organization invitation
/api/organization-invitations/{invitationId} - POST
createWorkspaceCreate a workspace
/api/organizations/{organizationId}/workspaces - GET
listOrganizationWorkspacesList organization workspaces
/api/organizations/{organizationId}/workspaces - GET
getWorkspaceGet a workspace
/api/organizations/{organizationId}/workspaces/{workspaceId} - GET
listWorkspaceMembersList the people who work in a workspace
/api/organizations/{organizationId}/workspaces/{workspaceId}/members - PATCH
renameWorkspaceRename a workspace
/api/organizations/{organizationId}/workspaces/{workspaceId} - DELETE
deleteWorkspaceDelete a workspace
/api/organizations/{organizationId}/workspaces/{workspaceId} - GET
getWorkspaceMapGet the workspace map
/api/organizations/{organizationId}/workspaces/{workspaceId}/map