Visão geral

O princípio que atravessa tudo

O Trivo não hospeda nem executa código de bot. Você roda o seu programa onde quiser, e ele se conecta à API REST e ao Gateway com uma credencial. Não há runtime, fila de jobs nem sandbox do nosso lado: só a ponte.

Um App é uma entidade própria, e nunca uma conta humana de mentira. Ele não tem senha, não faz login, não tem e-mail e não aceita termos. Na tela ele tem nome, avatar, perfil e o selo APP, que quem lê a mensagem enxerga.

O caminho é um só: o SDK

Apps do Trivo são desenvolvidos com o @trivo/sdk. Ele é a camada oficial, e é a única que esta documentação ensina — não existe um segundo jeito suportado de construir App. A razão é prática: assinatura de entrega, reconexão, retomada, Retry-After, contrapressão, ordenação e o contrato de erro são fáceis de implementar quase certo, e quase certo em autorização e em criptografia é errado.

pnpm add @trivo/sdk

O que o SDK usa por baixo — REST, Gateway, POST assinado — continua descrito aqui, em blocos marcados como referência de transporte. Eles existem para transparência, depuração e compatibilidade (escrever um cliente em outra linguagem, por exemplo), e não como um caminho paralelo.

As três superfícies que o SDK cobre

• REST — app.rest.*: você chama, o Trivo responde. É por aqui que o App escreve mensagem, reage, cria canal e mexe em cargo.
• Gateway — app.on(…): o Trivo empurra os eventos para você. É por aqui que o App fica sabendo do que acontece sem perguntar.
• Interações — app.onInteraction(…): alguém aciona algo do seu App e você tem poucos segundos para responder. Chegam pelo Gateway ou por um POST assinado no seu endpoint, e o seu código é o mesmo nos dois.

O contrato fala inglês; esta página, não

Tudo o que atravessa o fio está em inglês: nome de evento, nome de campo, código de erro, nome de intent. A prosa que explica é em português, porque ela é para gente ler. Não existe tabela de tradução entre as duas coisas: o nome público é escrito uma vez, e é a única forma dele.

A exceção são os nomes de permissão e de escopo, que viajam em português — gerenciar_canais, banir_membros. Eles são gravados no banco e aparecem na tela de autorização que uma pessoa lê: traduzi-los na borda criaria duas nomenclaturas para o mesmo poder, que é justamente o que esta régua existe para impedir.

{
  "type": "message_create",
  "serverId": "1234567890123456789",
  "message": {
    "publicId": "9876543210987654321",
    "channelId": "1111111111111111111",
    "author": { "publicId": "2222222222222222222", "displayName": "Ana" },
    "content": "olá",
    "createdAt": "2026-08-31T12:00:00.000Z",
    "editedAt": null
  }
}

author é anulável: mensagem de autor removido chega com null, e author.app: true diz que quem escreveu foi um App. Ramificar sem testar o nulo é o defeito que aparece meses depois, na primeira exclusão de conta.

Há uma exceção registrada e uma pendência conhecida. A exceção é key_id, na rota de chaves de assinatura: ele usa sublinhado no meio de um contrato camelCase porque é a mesma palavra que aparece dentro do cabeçalho x-trivo-signature. A pendência é o parâmetro antesDe, na paginação de mensagens, que continua em português.

Até onde um App chega

Três coisas ficam fora do alcance de qualquer App, e nenhuma delas é configuração: conversa privada (três camadas independentes a fecham), presença de gente e moderação sobre pessoas. É a pergunta que decide se vale integrar, e a resposta inteira — com as rotas que recusam Bearer e o que não existe — está em O que um App nunca alcança.

Por onde continuar

A ordem abaixo é a de leitura: o que é isto, como se constrói um, o que o App alcança, as três superfícies e, no fim, o que se consulta com pressa no meio de uma depuração.