Skip to main content
Toda organização tem exatamente dois ambientes, live e test, criados junto com ela. Não dá para criar nem deletar, e nunca existe um terceiro. As tabelas do plano de clientes carregam environment_id ao lado de organization_id. Dados de teste e dados de produção são o mesmo schema e nunca as mesmas linhas. A diferença entre os dois é o que as linhas significam, não o que elas podem fazer. Test não é uma cópia reduzida: os mesmos endpoints respondem, os mesmos webhooks disparam, os mesmos e-mails saem, os mesmos limites valem. O que separa os dois é que um guarda os seus clientes de verdade e o outro guarda o que você precisou enquanto construía — e que nada do que você faz em test é visto de dentro de live.

​
A credencial decide

É a regra em torno da qual o desenho inteiro gira. Na superfície de máquina, o ambiente é resolvido a partir da linha da chave armazenada, em toda requisição. Não de um header, não de um parâmetro de query, não de um campo no corpo. Não existe como nomear um.
O que significa:
  • um id de live buscado com uma chave de test responde 404 — e o 404 não revela que a linha existe em outro lugar;
  • um contato identificado com uma chave de test é inalcançável a partir de live;
  • apontar staging para produção não é um erro que se cometa num arquivo de config, porque não há campo para errar.
O tipo de ambiente é gravado no prefixo da chave, então uma chave que vaza diz na própria cara qual modo ela abre.
GET /v1/me é a forma mais barata de confirmar qual ambiente uma chave abre. Toda integração deveria chamá-lo uma vez no start-up.

​
O painel é a exceção

Staff é autorizado na organização inteira, então as leituras do painel recebem o ambiente como parâmetro explícito de visão:
O padrão é live. Qualquer coisa fora de live ou test responde 400 invalid_request. Essa é a postura oposta à da superfície de máquina, e segura exatamente por isso: quem chama já está autorizado nos dois ambientes, então deixar escolher não amplia alcance nenhum. Uma credencial de máquina não ganha esse parâmetro, jamais. Na interface do painel o ambiente ativo é uma preferência de visão no cliente, marcada pelo seletor no header e por uma faixa âmbar sempre que o modo de teste está ligado.

​
O segredo de identidade

Todo ambiente guarda um segredo de identidade — a chave HMAC com que o seu servidor assina valores de external_id. É por ambiente, criado na primeira leitura, e lê-lo exige api_keys:write: esse segredo emite sessões verificadas, então lê-lo é possuí-lo.
Rotacionar o substitui e mantém o anterior verificando por uma janela de carência de 24 horas — tempo suficiente para uma frota redeployar, curto o bastante para que um segredo antigo roubado tenha prazo.
Os dois endpoints respondem 501 federated_identity_unavailable quando o servidor não pode guardar o segredo cifrado com segurança.

​
O que os dois ambientes compartilham

Quase nada. Contatos, clientes, conversas, eventos, assinaturas e mensagens são por ambiente, e nada do que você faz em test é visível de live. A exceção é a sua central de ajuda. Os artigos pertencem à organização, não a um ambiente: existe uma só, publicada uma vez, e os dois ambientes a leem. Um artigo é algo que você escreveu, revisou e publicou, e diz a mesma coisa qualquer que seja o ambiente que pergunte. O que importa para a IA de suporte, porque ela responde a partir de dois tipos de material: Uma conversa resolvida é a transcrição do que foi digitado enquanto alguém construía: um ensaio, um widget testado com bobagem, um reembolso prometido a um contato que não existe. Isso é conhecimento sobre o seu ambiente de test, não sobre o seu produto, então nunca molda uma resposta enviada a um cliente de live — e as transcrições de live também não moldam uma resposta de test.
Um ambiente de test sem conversas resolvidas próprias responde apenas a partir dos seus artigos publicados. Sem artigos publicados também, a IA registra no_knowledge, escala a conversa e a deixa na caixa de entrada para uma pessoa. Essa é a resposta correta, não um erro de configuração: as transcrições de live são de live.
As respostas em cache seguem a mesma linha. Uma resposta é guardada por ambiente e aposentada sempre que o material por trás dela se move — a publicação de um artigo, ou a resolução de outra conversa naquele ambiente.