Pular para o conteúdo principal

Agências e workspaces

Uma agência que cuida do WhatsApp de vários clientes separa cada um num workspace: uma conta completa, com os próprios números, contatos, conversas, etiquetas, campos, públicos, supressões, fluxos, campanhas, modelos, chaves de API, webhooks e sites. Nada de um cliente aparece no outro. Todos os workspaces ficam na assinatura da agência: uma fatura só, com números, mensagens, contatos e assentos somados no grupo.

Os workspaces são criados e geridos no painel, na tela Workspaces da conta da agência. A API não cria nem apaga workspaces; o que muda para quem integra está abaixo.

Quantos. O dono da conta abre um workspace por número de WhatsApp que o plano permite, sem pedir nada a ninguém: um plano de três números cobre três clientes. Num plano sem limite de números, não há limite de workspaces.

Uma chave pertence a uma conta​

Uma chave de API é sempre de uma conta — a da agência ou a de um cliente — e só alcança o que é dela. Para integrar o site ou o sistema de um cliente, crie a chave dentro do workspace dele (entre no cliente pelo seletor de contas do painel e vá em Chaves de API). Uma chave da conta da agência não envia pelos números de um cliente, e a de um cliente não vê os outros.

O resto funciona como em qualquer conta: a chave pode ser limitada a alguns números, e os webhooks cadastrados num workspace recebem só os eventos daquele cliente.

Saber de quem é a conta​

GET /account/me traz parent: a agência que gerencia e paga a conta, quando ela é o workspace de um cliente, e null numa conta comum.

{
  "data": {
    "id": "cm1clinica",
    "name": "Clínica Sorriso",
    "parent": { "id": "cm1agencia", "name": "Agência Acme" },
    "wabas": []
  }
}

Cobrar cada cliente pelo que usou​

GET /workspaces, com a chave sem restrição de números da conta da agência, devolve o grupo: a conta da agência primeiro e depois cada workspace, com o consumo do período de cobrança (usage: números conectados, contatos e mensagens). É o número que a agência usa para repassar o custo a cada cliente.

curl https://api.joinotify.com/workspaces \
  -H "Authorization: Bearer sk_live_DA_AGENCIA"

A chave de um workspace recebe 409 not_principal, e uma chave limitada a números recebe 403: um cliente nunca fica sabendo dos outros.

Ler os contatos de todos os clientes​

GET /contacts?account=all, com a chave sem restrição de números da agência, lista os contatos da agência e de todos os workspaces, com os mesmos filtros da lista comum; ?account=<id do workspace> lista os de um cliente só. Cada contato traz workspace — o cliente de onde vem, ou null para os da própria agência.

Entregar ativos a um cliente​

Pelo painel, o dono da agência entrega ao workspace de um cliente o que estava na conta da agência: contatos (os que a agência ainda usa são copiados; os demais mudam de conta), um fluxo (copiado como rascunho) e uma chave de API. Uma chave entregue continua com o mesmo segredo: o que a integração mandar dali em diante cai no cliente. A chave também pode ser criada direto no workspace, a partir da conta da agência.

Dinheiro é da agência​

Dentro de um workspace não há assinatura, fatura, carteira nem programa de afiliados próprios. /wallet e /affiliate respondem 409 billed_by_parent com a chave de um workspace; o que se consulta sobre cobrança, consulta-se com a chave da agência.

Clientes que estavam misturados​

A agência que já atendia vários clientes numa conta só leva cada um para o seu workspace pelo painel, um WABA por vez: o WABA vem com os números, modelos, conversas, contatos e as chaves limitadas só a esses números. Depois disso, essas chaves passam a ser do workspace — a integração continua funcionando sem trocar a chave, mas GET /account/me passa a responder com o cliente e com parent.