API de Equipe #

Sua equipe é composta por todos que trabalham em sua conta além de você — administradores, agentes e visualizadores com permissão apenas de leitura — além dos convites que você enviou e os departamentos nos quais você os organiza. A API de Equipe é a versão programática de Configurações → Equipe: adicione e remova pessoas, defina o que cada uma delas pode ver e fazer, envie e acompanhe convites e gerencie departamentos.

Todos os endpoints abaixo são relativos à URL base https://api.youraiconnector.com/v1. Para a versão do painel de tudo nesta página, consulte Gerenciamento de Equipe.

Autenticação: estes endpoints exigem uma pessoa conectada #

Esta é a única parte da API que uma chave de API não pode usar. Cada endpoint /team, exceto os de departamento, deve ser chamado com um token de ID do Firebase de uma sessão conectada:

Authorization: Bearer <Firebase ID token>

Envie uma chave de API e a solicitação será rejeitada com um 401:

{
  "success": false,
  "error_code": 401,
  "error": "This endpoint requires a Firebase ID token (Authorization: Bearer <token>)."
}

O motivo é que esses endpoints decidem o que fazer com base em quem está conectado: sua função, o limite do que você tem permissão para conceder a outra pessoa e se você está trabalhando atualmente dentro de outra conta. Uma chave de API é uma integração, não uma pessoa, portanto, não há ninguém a quem essas regras possam ser aplicadas.

Na prática, isso significa que a API de Equipe é para um aplicativo de primeira parte com um usuário Your AI Connector conectado (consulte Autenticação → Token de ID do Firebase). Uma integração servidor-para-servidor não pode gerenciar membros da equipe — não há como criar um desses tokens de fora do aplicativo.

A exceção: os quatro endpoints de departamento são endpoints de API comuns. Eles aceitam sua chave de API exatamente como o restante da API, bem como uma sessão conectada.

Cada resposta nesta página segue o envelope usual: success: true mais os campos do endpoint no nível superior, ou success: false com error e error_code quando algo dá errado.

Funções e permissões #

Cada membro da equipe tem uma função, que define seu acesso padrão em 12 áreas do aplicativo. Você pode então substituir áreas individuais.

Cada área é definida como um dos quatro níveis: none (oculto), view (apenas leitura), edit (criar e alterar), full (incluindo exclusão).

Para desviar dos padrões da função, envie permission_overrides — uma matriz de objetos { "area": ..., "level": ... }. Cada entrada substitui o padrão da função para aquela área específica; tudo o que você não listar mantém o padrão da função.

"permission_overrides": [
  { "area": "analytics", "level": "full" },
  { "area": "billing", "level": "none" }
]

Quem pode chamar esses endpoints

• O proprietário da conta sempre pode fazer tudo.
• Um membro da equipe precisa de team_management em view para ler a lista de membros e a lista de convites, e em edit para adicionar, alterar, suspender, remover, convidar, cancelar ou reenviar. Administradores têm edit por padrão; editores e visualizadores têm none, portanto, por padrão, apenas administradores podem gerenciar a equipe.
• Ninguém pode conceder acesso superior ao seu próprio. Se você tentar dar a alguém um nível que você mesmo não possui — ou editar, suspender ou remover alguém cujo acesso já seja mais amplo que o seu — a solicitação será recusada com 403 e uma mensagem nomeando a área.

O objeto de membro da equipe #

GET /team/members retorna um destes por membro:

Membros removidos não são retornados — a lista contém apenas membros ativos e suspensos.

Limites de visibilidade são apenas de escrita aqui. contact_scope, contact_scope_axes e sub_account_access (veja Limitando o que um membro pode ver) podem ser definidos na criação, atualização e convite, mas este endpoint não os retorna.

Listar membros da equipe #

GET /team/members

Retorna a lista de membros mais as contagens de assentos do seu plano, para que você possa exibir “3 de 5 assentos” e saber quando um convite está prestes a ser recusado.

cURL

curl "https://api.youraiconnector.com/v1/team/members" \
  -H "Authorization: Bearer FIREBASE_ID_TOKEN"

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/team/members", {
  headers: { Authorization: `Bearer ${idToken}` },
});
const { members, seat_limit, seats_used } = await res.json();

Python

import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/team/members",
    headers={"Authorization": f"Bearer {id_token}"},
)
data = res.json()

Resposta

{
  "success": true,
  "members": [
    {
      "account_owner_uid": "owner_uid_123",
      "member_uid": "uid_alice",
      "member_email": "alice@example.com",
      "member_display_name": "Alice Chen",
      "role": "admin",
      "permission_overrides": [],
      "status": "active",
      "auto_assign_enabled": true,
      "created_by": "owner_uid_123",
      "created_at": "2026-05-01T10:00:00.000Z",
      "updated_at": "2026-06-02T09:15:00.000Z"
    }
  ],
  "seat_limit": 5,
  "seats_used": 3
}

seat_limit é null quando seu plano não tem limite de assentos. seats_used conta apenas membros ativos — suspender ou remover alguém libera seu assento imediatamente.

Adicionar um membro da equipe diretamente #

POST /team/members

Coloca alguém em sua equipe imediatamente, sem um convite.

Isso não envia nenhum e-mail. Ninguém é avisado de que foi adicionado e, se a pessoa ainda não tiver um login Your AI Connector, a conta criada para ela não terá senha, portanto, ela não poderá entrar até que a redefina. Use Enviar um convite, a menos que você tenha sua própria maneira de avisar a pessoa e ajudá-la a entrar.

Campos da requisição

cURL

curl -X POST "https://api.youraiconnector.com/v1/team/members" \
  -H "Authorization: Bearer FIREBASE_ID_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "sam@example.com",
    "display_name": "Sam Rivera",
    "role": "editor"
  }'

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/team/members", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${idToken}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    email: "sam@example.com",
    display_name: "Sam Rivera",
    role: "editor",
  }),
});
const { member_uid } = await res.json();

Resposta — 201 Created

{
  "success": true,
  "team_member_id": "owner_uid_123_uid_sam",
  "member_uid": "uid_sam",
  "message": "Team member created successfully."
}

Adicionar alguém que foi anteriormente suspenso ou removido o reintegra em vez de falhar.

Atualizar um membro da equipe #

PATCH /team/members/{memberUid}

Altera a função, permissões, visibilidade, acesso do cliente ou se um membro participa da atribuição automática de contatos. Envie apenas os campos que deseja alterar; tudo o que você omitir manterá seu valor atual.

Campos da requisição

Este é o único endpoint onde null significa “limpar”. Enviar "contact_scope": null, "contact_scope_axes": null ou "sub_account_access": null remove esse limite completamente e faz com que o membro volte a ver tudo. Na criação e no convite, null simplesmente significa “não fornecido”.

cURL

curl -X PATCH "https://api.youraiconnector.com/v1/team/members/uid_sam" \
  -H "Authorization: Bearer FIREBASE_ID_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "role": "admin",
    "permission_overrides": [{ "area": "billing", "level": "none" }]
  }'

Resposta

{
  "success": true,
  "message": "Team member updated successfully."
}

Suspender um membro da equipe #

POST /team/members/{memberUid}/suspend

Suspende alguém: a pessoa mantém seu lugar na equipe, mas perde o acesso. Use isso em vez de remover quando a pausa for temporária — traga-a de volta com PATCH /team/members/{memberUid} e {"status": "active"}.

cURL

curl -X POST "https://api.youraiconnector.com/v1/team/members/uid_sam/suspend" \
  -H "Authorization: Bearer FIREBASE_ID_TOKEN"

Resposta

{
  "success": true,
  "message": "Team member suspended successfully."
}

Um membro suspenso libera sua vaga, para que você possa convidar outra pessoa em seu lugar. O acesso dele termina quando o token de sessão atual for atualizado, o que pode levar até uma hora — remova-o se precisar que seja imediato.

Remover um membro da equipe #

DELETE /team/members/{memberUid}

Remove alguém da sua equipe e libera a sua licença. A pessoa é desconectada e perde o acesso à sua conta; o login dela permanece inalterado.

cURL

curl -X DELETE "https://api.youraiconnector.com/v1/team/members/uid_sam" \
  -H "Authorization: Bearer FIREBASE_ID_TOKEN"

Resposta

{
  "success": true,
  "message": "Team member removed successfully."
}

A remoção é permanente do seu lado: um membro removido não pode ser reativado com o endpoint de atualização — convide-o novamente se mudar de ideia. O e-mail dele também é removido da lista de notificações da sua conta.

Limitando o que um membro pode ver #

Três campos opcionais, aceitos em adicionar, atualizar e convidar, determinam quanto da conta uma pessoa pode ver. Eles se acumulam: um membro limitado em mais de um campo é limitado por todos eles.

contact_scope — all (o padrão: todos os contatos e conversas) ou assigned (apenas aqueles atribuídos a eles). Com assigned, adicione "contact_scope_unassigned": true para também permitir que vejam contatos que ainda não possuem proprietário.

contact_scope_axes — limita-os a agentes, canais ou departamentos nomeados:

Os IDs de agentes e departamentos não são verificados quando você os salva — um ID que não existe simplesmente não corresponde a nada, o que aparece como uma caixa de entrada vazia em vez de um erro. Os nomes dos canais são verificados: um nome não reconhecido é rejeitado com 400.

Nenhum desses três pode ser definido para o proprietário da conta — essa solicitação é recusada com 400.

Listar convites #

GET /team/invites

Os convites que você enviou, do mais recente para o mais antigo, para que você possa ver quem ainda não aceitou.

Parâmetros de consulta

cURL

curl "https://api.youraiconnector.com/v1/team/invites?status=pending" \
  -H "Authorization: Bearer FIREBASE_ID_TOKEN"

Resposta

{
  "success": true,
  "invites": [
    {
      "id": "inv_abc123",
      "account_owner_uid": "owner_uid_123",
      "account_owner_display_name": "Acme Ltd",
      "invitee_email": "sam@example.com",
      "invitee_uid": null,
      "role": "editor",
      "permission_overrides": [],
      "status": "pending",
      "created_by": "owner_uid_123",
      "created_at": "2026-06-10T12:00:00.000Z",
      "expires_at": "2026-06-17T12:00:00.000Z",
      "responded_at": null
    }
  ]
}

O token do convite nunca é retornado — ele só existe no e-mail que foi enviado.

Enviar um convite #

POST /team/invites

Envia por e-mail um convite para alguém entrar na sua equipe. Esta é a maneira usual de adicionar um colega de equipe: ele clica no link, faz login com sua própria conta e aceita. Se ele ainda não tiver uma conta Your AI Connector, uma será criada para ele e o e-mail o guiará na definição de uma senha.

Campos da requisição

Configurar as permissões antecipadamente significa que você não precisa editar o membro posteriormente — tudo é copiado para a associação dele quando ele aceita.

cURL

curl -X POST "https://api.youraiconnector.com/v1/team/invites" \
  -H "Authorization: Bearer FIREBASE_ID_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "email": "sam@example.com", "role": "editor" }'

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/team/invites", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${idToken}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ email: "sam@example.com", role: "editor" }),
});
const { invite_id } = await res.json();

Resposta — 201 Created

{
  "success": true,
  "invite_id": "inv_abc123",
  "message": "Team invite sent successfully."
}

Coisas a planejar

• Os convites expiram após 7 dias. Um convite expirado pode ser reenviado, o que inicia um novo período de 7 dias.
• Convites pendentes ocupam uma vaga. Ao contrário de adicionar um membro diretamente, a verificação de vagas aqui conta os membros ativos mais os convites pendentes, portanto, uma conta com todas as vagas ocupadas será recusada antes que o e-mail seja enviado.
• 20 convites por dia, contados por conta, tanto para envio quanto para reenvio.

Cancelar um convite #

DELETE /team/invites/{inviteId}

Retira um convite antes que ele seja aceito. O link no e-mail para de funcionar.

cURL

curl -X DELETE "https://api.youraiconnector.com/v1/team/invites/inv_abc123" \
  -H "Authorization: Bearer FIREBASE_ID_TOKEN"

Resposta

{
  "success": true,
  "message": "Team invite cancelled."
}

Tanto convites pending quanto expired podem ser cancelados. Um convite que já foi aceito, recusado ou cancelado retorna 400; um que não é seu retorna 403; um ID desconhecido retorna 404.

Reenviar um convite #

POST /team/invites/{inviteId}/resend

Envia o e-mail de convite novamente — para quando ele foi perdido ou foi para o spam. Funciona em convites pending e expired, e redefine a expiração para 7 dias a partir de agora.

cURL

curl -X POST "https://api.youraiconnector.com/v1/team/invites/inv_abc123/resend" \
  -H "Authorization: Bearer FIREBASE_ID_TOKEN"

Resposta

{
  "success": true,
  "message": "Team invite resent successfully."
}

O novo e-mail traz um novo link, e o link antigo continua funcionando também, para que uma pessoa que encontre o primeiro e-mail mais tarde não fique impedida. O reenvio conta para o mesmo limite de 20 por dia que o envio, e reativar um convite expirado verifica novamente suas vagas — um plano completo é recusado com 429.

Aceitar um convite #

POST /team/invites/accept

Aceita um convite com o token do e-mail de convite, adicionando a pessoa conectada à equipe daquela conta.

Este é um ato da sua própria identidade. Entre como você mesmo — isso é deliberadamente recusado com 403 enquanto você estiver trabalhando dentro da conta de outra pessoa.

Campos da requisição

cURL

curl -X POST "https://api.youraiconnector.com/v1/team/invites/accept" \
  -H "Authorization: Bearer FIREBASE_ID_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "invite_token": "1f4c…" }'

Resposta

{
  "success": true,
  "team_member_id": "owner_uid_123_uid_sam",
  "account_owner_uid": "owner_uid_123",
  "message": "Team invite accepted successfully."
}

Recusar um convite #

POST /team/invites/decline

Recusa um convite com o token do e-mail. Assim como aceitar, este é um ato da sua própria identidade e é recusado enquanto você estiver trabalhando dentro de outra conta.

cURL

curl -X POST "https://api.youraiconnector.com/v1/team/invites/decline" \
  -H "Authorization: Bearer FIREBASE_ID_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "invite_token": "1f4c…" }'

Resposta

{
  "success": true,
  "message": "Team invite declined."
}

Departamentos #

Um departamento é um grupo nomeado da sua equipe — Vendas, Suporte ao cliente, RH. Ele atribui uma equipe responsável a um lead, pode assumir novas conversas por conta própria e pode ser usado para limitar o que um membro vê.

Estes quatro endpoints exigem uma chave de API. Diferente do restante desta página, eles autenticam como qualquer outro endpoint na API (consulte Autenticação). Uma sessão iniciada também funciona: a leitura requer contacts em view, e criar, alterar ou excluir requer team_management em edit.

O objeto departamento

Quando routing_agents e routing_channels estão definidos, uma conversa precisa corresponder a ambos para ser registrada aqui — é assim que você dá a uma equipe “o agente de suporte, mas apenas no WhatsApp”.

Uma conta pode ter até 50 departamentos.

Listar departamentos #

GET /team/departments

curl "https://api.youraiconnector.com/v1/team/departments?apiKey=YOUR_API_KEY"

Resposta

{
  "success": true,
  "departments": [
    {
      "id": "dep_abc123",
      "name": "Sales",
      "color": "#2f6fed",
      "member_uids": ["uid_alice", "uid_bob"],
      "auto_assign_enabled": true,
      "routing_agents": [],
      "routing_channels": ["whatsapp"],
      "created_by": "owner_uid_123"
    }
  ]
}

Criar um departamento #

POST /team/departments

Campos da requisição

cURL

curl -X POST "https://api.youraiconnector.com/v1/team/departments?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Sales",
    "color": "#2f6fed",
    "member_uids": ["uid_alice", "uid_bob"],
    "routing_channels": ["whatsapp"]
  }'

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/team/departments", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    name: "Sales",
    color: "#2f6fed",
    member_uids: ["uid_alice", "uid_bob"],
    routing_channels: ["whatsapp"],
  }),
});
const { department } = await res.json();

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/team/departments",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "name": "Sales",
        "color": "#2f6fed",
        "member_uids": ["uid_alice", "uid_bob"],
        "routing_channels": ["whatsapp"],
    },
)
department = res.json()["department"]

Resposta — 201 Created

{
  "success": true,
  "department": {
    "id": "dep_abc123",
    "name": "Sales",
    "color": "#2f6fed",
    "member_uids": ["uid_alice", "uid_bob"],
    "auto_assign_enabled": true,
    "routing_agents": [],
    "routing_channels": ["whatsapp"],
    "created_by": "owner_uid_123"
  }
}

Atualizar um departamento #

PATCH /team/departments/{departmentId}

Altera um departamento. Apenas os campos que você enviar serão alterados.

curl -X PATCH "https://api.youraiconnector.com/v1/team/departments/dep_abc123?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "member_uids": ["uid_alice"], "auto_assign_enabled": false }'

Resposta

{
  "success": true,
  "department": {
    "id": "dep_abc123",
    "name": "Sales",
    "color": "#2f6fed",
    "member_uids": ["uid_alice"],
    "auto_assign_enabled": false,
    "routing_agents": [],
    "routing_channels": ["whatsapp"],
    "created_by": "owner_uid_123"
  }
}

O envio de campos não reconhecidos retorna 400; um departamento desconhecido retorna 404; um nome que entra em conflito com outro departamento retorna 409.

Excluir um departamento #

DELETE /team/departments/{departmentId}

curl -X DELETE "https://api.youraiconnector.com/v1/team/departments/dep_abc123?apiKey=YOUR_API_KEY"

Resposta

{
  "success": true,
  "deleted": "dep_abc123"
}

A exclusão de um departamento ao qual alguém está limitado é recusada. A resposta 400 nomeia os membros cuja visibilidade está restrita a ele, para que você possa redefinir o escopo deles primeiro. Isso é intencional: removê-los do limite silenciosamente entregaria a eles toda a sua base de clientes sem que houvesse qualquer indicação de que isso aconteceu.

Os contatos arquivados em um departamento excluído não são reescritos — eles simplesmente param de exibir um departamento, e na próxima vez que você os arquivar, a alteração será aplicada.

Verifique suas próprias permissões #

GET /team/permissions

Retorna o que a pessoa conectada tem permissão para fazer na conta em que está trabalhando no momento. Use isso para ocultar botões que um membro não pode usar, em vez de permitir que ele descubra o limite por meio de um erro.

cURL

curl "https://api.youraiconnector.com/v1/team/permissions" \
  -H "Authorization: Bearer FIREBASE_ID_TOKEN"

Resposta — o proprietário da conta

{
  "success": true,
  "role": "owner",
  "is_team_mode": false,
  "permissions": {
    "campaigns": "full",
    "contacts": "full",
    "messages": "full",
    "appointments": "full",
    "settings": "full",
    "billing": "full",
    "team_management": "full",
    "analytics": "full",
    "phone_numbers": "full",
    "integrations": "full",
    "faqs": "full",
    "daily_summaries": "full"
  }
}

Resposta — um membro da equipe trabalhando dentro de uma conta

{
  "success": true,
  "role": "editor",
  "is_team_mode": true,
  "permissions": { "campaigns": "edit", "billing": "none", "…": "…" },
  "member": {
    "uid": "uid_sam",
    "email": "sam@example.com",
    "display_name": "Sam Rivera",
    "account_owner_uid": "owner_uid_123"
  }
}

role é owner quando a pessoa conectada é o proprietário da conta; caso contrário, é a sua função na equipe. member só está presente no modo de equipe e carrega contact_scope, contact_scope_unassigned e contact_scope_axes quando a sua associação os possui.

Tokens de sessão #

Cinco endpoints criam um token de login de uso único para alternar entre contas. Todos eles respondem da mesma maneira:

{
  "success": true,
  "customToken": "eyJhbGciOi…"
}

O token é trocado por uma sessão com o SDK do cliente Firebase. Ele não é uma chave de API e não pode ser enviado como tal, e é por isso que esses endpoints só são úteis dentro de um aplicativo próprio.

Cada um recusa com 403 quando a sessão não tem direito a isso: não é um membro daquela conta, não é da equipe, aquela subconta não está na sua agência ou não foi concedida a você, ou a sessão não está atualmente no modo que o endpoint termina.

Atribuir uma função de plataforma #

POST /team/users/{targetUid}/role

Define a função de plataforma de um usuário — User, Dev, Support ou Agency. Isso não é associação de equipe: é que tipo de conta Your AI Connector alguém possui.

Este endpoint é restrito a funcionários Your AI Connector, e o último Dev restante não pode ser rebaixado. Listado por completude; não faz parte do gerenciamento da sua própria equipe.

{
  "success": true,
  "targetUid": "uid_sam",
  "role": "Agency",
  "claimUpdated": true
}

Erros da API de Equipe #

Os endpoints de equipe retornam o envelope de erro padrão, sempre com error_code junto com o status HTTP:

{
  "success": false,
  "error_code": 403,
  "error": "Cannot grant \"full\" access to \"billing\" — exceeds your own permissions."
}

Os códigos compartilhados que todo endpoint pode retornar — 429 (limite de taxa) e 500 — estão listados com orientações de nova tentativa em Erros e Paginação.

Relacionado #

• Gerenciamento de Equipe — os mesmos recursos no painel, com capturas de tela.
• Autenticação — como enviar um token de ID do Firebase em vez de uma chave de API.
• API de Contatos — os contatos aos quais os limites de visibilidade de um membro se aplicam.