Skip to main content

​
Pré-requisitos

  • API Key com escopos: workspace:read (ler), workspace:create (criar), workspace:update (editar), workspace:delete (deletar).
  • Envie a API Key em toda requisição:
    • Header: Authorization: Bearer sk_live_xxxxx
    • ou Header: x-api-key: sk_live_xxxxx
A API Key está vinculada a um workspace. Em ler, editar e deletar, o :id da URL deve ser o ID desse workspace — não é possível acessar workspaces de outros.

​
1. Criar workspace

Cria um novo workspace para o mesmo usuário dono do workspace da API Key. O usuário é identificado pelo membro OWNER do workspace atual. Respeita o limite de workspaces por usuário (ex.: 3). Request 
POST /v1/workspaces
Content-Type: application/json
Authorization: Bearer sk_live_xxxxx

{
  "name": "Meu Novo Workspace",
  "color": "#3B82F6"
}
Response (200) 
{
  "success": true,
  "data": {
    "id": "clxx...",
    "name": "Meu Novo Workspace",
    "slug": "meu-novo-workspace-42",
    "color": "#3B82F6",
    "createdAt": "2025-02-23T10:00:00.000Z"
  }
}
Nome: 1–64 caracteres. Cor opcional (7 caracteres, Hexadecimal). Se o limite de workspaces do usuário for atingido, retorna 403 com código WORKSPACE_SLOTS_LIMIT_REACHED.

​
2. Obter workspace

Retorna o workspace da API Key. Requer escopo workspace:read. Request 
GET /v1/workspaces/:id
Authorization: Bearer sk_live_xxxxx
Response (200) 
{
  "success": true,
  "data": {
    "id": "clxx...",
    "name": "Meu Workspace",
    "slug": "meu-workspace-123",
    "color": "#10B981",
    "defaultInstanceId": "clzz...",
    "defaultEmailDomainId": null,
    "groupFeaturesEnabled": false,
    "inboundSettings": {
      "version": 1,
      "channels": {
        "sms": { "enabled": true },
        "whatsapp": {
          "enabled": true,
          "allowPrivateChats": true,
          "allowGroupChats": true
        },
        "email": { "enabled": true }
      }
    },
    "updatedAt": "2025-02-23T10:30:00.000Z"
  }
}
groupFeaturesEnabled indica se os recursos experimentais de grupos WhatsApp estão ativados (ver Recursos experimentais na Introdução). inboundSettings traz a política efetiva de inbound do workspace.

​
3. Editar workspace

Atualiza o workspace. Apenas o workspace da API Key pode ser editado (:id = ID desse workspace). Campos opcionais: nome, cor, instância WhatsApp padrão, domínio de e-mail padrão, groupFeaturesEnabled (recursos experimentais de grupos) e inboundSettingsPatch (patch parcial da política de inbound). Request 
PUT /v1/workspaces/:id
Content-Type: application/json
Authorization: Bearer sk_live_xxxxx

{
  "name": "Workspace Renomeado",
  "color": "#10B981",
  "defaultInstanceId": "clzz...",
  "defaultEmailDomainId": null,
  "groupFeaturesEnabled": false,
  "inboundSettingsPatch": {
    "channels": {
      "sms": { "enabled": true },
      "whatsapp": {
        "enabled": true,
        "allowPrivateChats": true,
        "allowGroupChats": false
      }
    }
  }
}
Response (200) 
{
  "success": true,
  "data": {
    "id": "clxx...",
    "name": "Workspace Renomeado",
    "slug": "meu-workspace-123",
    "color": "#10B981",
    "defaultInstanceId": "clzz...",
    "defaultEmailDomainId": null,
    "groupFeaturesEnabled": false,
    "inboundSettings": {
      "version": 1,
      "channels": {
        "sms": { "enabled": true },
        "whatsapp": {
          "enabled": true,
          "allowPrivateChats": true,
          "allowGroupChats": false
        },
        "email": { "enabled": true }
      }
    },
    "updatedAt": "2025-02-23T10:30:00.000Z"
  }
}
defaultInstanceId e defaultEmailDomainId devem pertencer ao workspace; caso contrário retorna 400. groupFeaturesEnabled ativa os recursos experimentais de grupos WhatsApp (API documentada em OpenAPI exclusivo, oculto por padrão). inboundSettingsPatch faz merge parcial com a configuração atual (não precisa enviar tudo de uma vez). Campos aceitos:
  • channels.sms.enabled
  • channels.whatsapp.enabled
  • channels.whatsapp.allowPrivateChats
  • channels.whatsapp.allowGroupChats
  • channels.email.enabled

​
4. Deletar workspace

Remove o workspace. Apenas o workspace da API Key pode ser deletado (:id = ID desse workspace). Regra: o usuário deve ter pelo menos 2 workspaces — não é permitido deletar o último (retorna 400 com código LAST_WORKSPACE). Request 
DELETE /v1/workspaces/:id
Authorization: Bearer sk_live_xxxxx
Response (200) 
{
  "success": true,
  "message": "Workspace deleted successfully"
}

​
Resumo do fluxo

  1. GET /v1/workspaces/:id → obter o workspace da API Key (escopo workspace:read).
  2. POST /v1/workspaces com name (e opcionalmente color) → criar novo workspace para o mesmo usuário.
  3. PUT /v1/workspaces/:id com name, color, defaultInstanceId, defaultEmailDomainId, groupFeaturesEnabled, inboundSettingsPatch (opcionais) → editar o workspace da API Key.
  4. DELETE /v1/workspaces/:id → deletar o workspace da API Key (desde que não seja o último do usuário).